.\" Man page generated from reStructuredText.
.
.TH "OPENNDS" "1" "Jan 06, 2021" "8.0.0" "openNDS"
.SH NAME
opennds \- opennds Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
openNDS is a high performance, small footprint Captive Portal,
offering by default a simple splash page restricted Internet connection, yet incorporates an API that allows the creation of sophisticated authentication applications.
.sp
It is a fork of the NoDogSplash project that in turn was derived originally from the codebase of the Wifi Guard Dog project.
.sp
openNDS is released under the GNU General Public License.
.INDENT 0.0
.IP \(bu 2
openNDS: \fI\%https://github.com/openNDS/openNDS\fP
.IP \(bu 2
Original Homepage \fIdown\fP: \fI\%http://kokoro.ucsd.edu/nodogsplash\fP
.IP \(bu 2
Archive: \fI\%https://web.archive.org/web/20140210131130/http://kokoro.ucsd.edu/nodogsplash\fP
.IP \(bu 2
Wifidog: \fI\%http://dev.wifidog.org/\fP
.IP \(bu 2
NoDogSplash: \fI\%https://github.com/nodogsplash/nodogsplash\fP
.IP \(bu 2
GNU GPL: \fI\%http://www.gnu.org/copyleft/gpl.html\fP
.UNINDENT
.sp
The following describes what openNDS does, how to get it and run it, and
how to customize its behavior for your application.
.sp
Contents:
.SH OVERVIEW
.sp
\fBopenNDS\fP (NDS) is a high performance, small footprint Captive Portal, offering by default a simple splash page restricted Internet connection, yet incorporates an API that allows the creation of sophisticated authentication applications.
.SS Captive Portal Detection (CPD)
.INDENT 0.0
.INDENT 3.5
All modern mobile devices, most desktop operating systems and most browsers now have a CPD process that automatically issues a port 80 request on connection to a network. NDS detects this and serves a special "\fBsplash\fP" web page to the connecting client device.
.UNINDENT
.UNINDENT
.SS Provide simple and immediate public Internet access
.INDENT 0.0
.INDENT 3.5
NDS provides two pre\-installed methods.
.INDENT 0.0
.IP \(bu 2
\fBClick to Continue\fP\&. A simple static web page with template variables (\fIdefault\fP). This provides basic notification and a simple click/tap to continue button.
.IP \(bu 2
\fBusername/email\-address login\fP\&. A simple dynamic set of web pages that provide username/email\-address login, a welcome page and logs access by client users. (\fIInstalled by default and enabled in the configuration file\fP)
.UNINDENT
.INDENT 0.0
.INDENT 3.5
Customising the page seen by users is a simple matter of editing the script file.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Write Your Own Captive Portal.
.INDENT 0.0
.INDENT 3.5
NDS can be used as the "Engine" behind the most sophisticated Captive Portal systems using the tools provided.
.INDENT 0.0
.IP \(bu 2
\fBForward Authentication Service (FAS)\fP\&. FAS provides pre\-authentication user validation in the form of a set of dynamic web pages, typically served by a web service independent of NDS, located remotely on the Internet, on the local area network or on the NDS router.
.IP \(bu 2
\fBPreAuth\fP\&. A special case of FAS that runs locally on the NDS router with dynamic html served by NDS itself. This requires none of the overheads of a full FAS implementation and is ideal for NDS routers with limited RAM and Flash memory.
.IP \(bu 2
\fBBinAuth\fP\&. A method of running a post authentication script or extension program.
.UNINDENT
.UNINDENT
.UNINDENT
.SH WHAT'S NEW? - CHANGELOG
.sp
openNDS (8.0.0)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This version introduces major new functionality and some major changes
.IP \(bu 2
Rationalisation of support for multiple Linux distributions [bluewavenet]
.IP \(bu 2
Refactor login.sh script introducing base64 encoding and hashed token (hid) support [bluewavenet]
.IP \(bu 2
Refactor fas\-hid script introducing base64 encoding and simplifying customisation of the script [bluewavenet]
.IP \(bu 2
Refactor binauth_log.sh and log BinAuth custom data as url encoded [bluewavenet]
.IP \(bu 2
Refactor fas\-aes, simplifying customisation of the script [bluewavenet]
.IP \(bu 2
Refactor fas\-aes\-https, simplifying customisation of the script [bluewavenet]
.IP \(bu 2
Change \- Use hid instead of tok when fas_secure_enabled >= 1 [bluewavenet]
.IP \(bu 2
Add \- base64 encoding to fas_secure_enabled level 1 [bluewavenet]
.IP \(bu 2
Add \- gatewyname, clientif, session_start, session_end and last_active to ndsctl json [bluewavenet]
.IP \(bu 2
Add \- support for RFC6585 Status Code 511 \- Network Authentication Required [bluewavenet]
.IP \(bu 2
Add \- Client Status Page UI with Logout [bluewavenet]
.IP \(bu 2
Add \- GatewayFQDN option [bluewavenet]
.IP \(bu 2
Add \- client interface to status page query string [bluewavenet]
.IP \(bu 2
Add \- support using base 64 encoded custom string for BinAuth and replace tok with hid [bluewavenet]
.IP \(bu 2
Add \- base 64 decode option to ndsctl [bluewavenet]
.IP \(bu 2
Add \- b64 encoding of querystring for level 1 [bluewavenet]
.IP \(bu 2
Add \- Improved performance/user\-experience on congested/slow systems using php FAS scripts [bluewavenet]
.IP \(bu 2
Add \- support for ndsctl auth by hid in client_list [bluewavenet]
.IP \(bu 2
Add \- Ensure faskey is set to default value (always enabled) [bluewavenet]
.IP \(bu 2
Add \- Display error page on login failure in login.sh [bluewavenet]
.IP \(bu 2
Add \- splash.html, add deprecation notice [bluewavenet]
.IP \(bu 2
Add \- authmon, improved lock checking and introduce smaller loopinterval [bluewavenet]
.IP \(bu 2
Add \- client_params, wait for ndsctl if it is busy [bluewavenet]
.IP \(bu 2
Add \- fas\-aes\-https, allow progressive output to improve user experience on slow links [bluewavenet]
.IP \(bu 2
Fix \- Block access to /opennds_preauth/ if PreAuth not enabled [bluewavenet]
.IP \(bu 2
Fix \- On startup, call iptables_fw_destroy before doing any other setup [bluewavenet]
.IP \(bu 2
Fix \- missing final redirect to originurl in fas\-hid [bluewavenet]
.IP \(bu 2
Fix \- ensure gatewayname is always urlencoded [bluewavenet]
.IP \(bu 2
Fix \- client session end not set by binauth [bluewavenet]
.IP \(bu 2
Fix \- Session timeout, if client setting is 0, default to global value [bluewavenet]
.IP \(bu 2
Fix \- missing trailing separator on query and fix some compiler errors [bluewavenet]
.IP \(bu 2
Fix \- ensure authmon daemon is killed if left running from previous crash [bluewavenet]
.IP \(bu 2
Fix \- add missing query separator for custom FAS parameters [bluewavenet]
.IP \(bu 2
Fix \- ndsctl auth, do not set quotas if client is already authenticated [bluewavenet]
.IP \(bu 2
Fix \- client_params, show "Unlimited" when "null" is received from ndsctl json [bluewavenet]
.IP \(bu 2
Update configuration files [bluewavenet]
.IP \(bu 2
update documentation [bluewavenet]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Sat, 2 Jan 2021 16:38:14 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (7.0.1)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This version contains fixes and some minor updates
.IP \(bu 2
Fix \- Failure of Default Dynamic Splash page on some operating systems [bluewavenet]
.IP \(bu 2
Fix \- A compiler warning \- some compiler configurations were aborting compilation [bluewavenet]
.IP \(bu 2
Update \- Added helpful comments in configuration files [bluewavenet]
.IP \(bu 2
Remove \- references to deprecated RedirectURL in opennde.conf [bluewavenet]
.IP \(bu 2
Update \- Documentation updates and corrections [bluewavenet]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Wed, 7 Nov 2020 12:40:33 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (7.0.0)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This version introduces major new enhancements and the disabling or removal of deprecated functionality
.IP \(bu 2
Fix \- get_iface_ip in case of interface is vif or multihomed [bluewavenet]
.IP \(bu 2
Fix \- Add missing client identifier argument in ndsctl help text [bluewavenet]
.IP \(bu 2
Deprecate \- ndsctl clients option [bluewavenet]
.IP \(bu 2
Add \- global quotas to output of ndsctl status [bluewavenet]
.IP \(bu 2
Fix \- fix missing delimiter in fas\-hid [bluewavenet]
.IP \(bu 2
Add \- Report Rate Check Window in ndsctl status and show client quotas [bluewavenet]
.IP \(bu 2
Add \- Quota and rate reporting to ndsctl json. Format output and fix json syntax errors [bluewavenet]
.IP \(bu 2
Fix \- get_client_interface for case of iw utility not available [bluewavenet]
.IP \(bu 2
Fix \- php notice for pedantic php servers in post\-request [bluewavenet]
.IP \(bu 2
Add \- built in autonomous Walled Garden operation [bluewavenet]
.IP \(bu 2
Remove \- support for deprecated RedirectURL [bluewavenet]
.IP \(bu 2
Add \- gatewaymac to the encrypted query string [bluewavenet]
.IP \(bu 2
Deprecate \- legacy splash.html and disable it [bluewavenet]
.IP \(bu 2
Add \- support for login mode in PreAuth  [bluewavenet]
.IP \(bu 2
Add \- Support for Custom Parameters [bluewavenet]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Wed, 5 Nov 2020 18:22:32 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (6.0.0)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This version \- for Openwrt after 19.07 \- for compatibility with new MHD API
.IP \(bu 2
Set \- minimum version of MHD to 0.9.71 for new MHD API [bluewavenet]
.IP \(bu 2
Set \- use_outdated_mhd to 0 (disabled) as default [bluewavenet]
.IP \(bu 2
Add \- Multifield PreAuth login script with css update [bluewavenet]
.IP \(bu 2
Add \- Documentation and config option descriptions for configuring Walled Garden IP Sets
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Wed, 21 Aug 2020 15:43:47 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (5.2.0)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This version \- for backport to Openwrt 19.07 \- for compatibility with old MHD API
.IP \(bu 2
Fix \- Failure of MHD with some operating systems eg Debian [bluewavenet]
.IP \(bu 2
Fix \- potential buffer truncation in ndsctl
.IP \(bu 2
Set \- use_outdated_mhd to 1 (enabled) as default [bluewavenet]
.IP \(bu 2
Set \- maximum permissible version of MHD to 0.9.70 to ensure old MHD API is used [bluewavenet]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Wed, 12 Aug 2020 17:43:57 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (5.1.0)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Add \- Generic Linux \- install opennds.service [bluewavenet]
.IP \(bu 2
Add \- Documentation updates [bluewavenet]
.IP \(bu 2
Add \- config file updates [bluewavenet]
.IP \(bu 2
Add \- Install sitewide username/password splash support files [bluewavenet]
.IP \(bu 2
Add \- quotas to binauth_sitewide [bluewavenet]
.IP \(bu 2
Add \- Splash page updates [bluewavenet]
.IP \(bu 2
Add \- Implement Rate Quotas [bluewavenet]
.IP \(bu 2
Fix \- check if idle preauthenticated [bluewavenet]
.IP \(bu 2
Add \- support for rate quotas [bluewavenet]
.IP \(bu 2
Fix \- Correctly compare client counters and clean up debuglevel messages [bluewavenet]
.IP \(bu 2
Add \- Implement upload/download quotas Update fas\-aes\-https to support quotas [bluewavenet]
.IP \(bu 2
Add \- Rename demo\-preauth scripts and install all scripts [bluewavenet]
.IP \(bu 2
Add \- fas\-aes\-https layout update [bluewavenet]
.IP \(bu 2
Add \- Set some defaults in fas\-aes\-https [bluewavenet]
.IP \(bu 2
Add \- custom data string to ndsctl auth [bluewavenet]
.IP \(bu 2
Add \- custom data string to fas\-hid.php [bluewavenet]
.IP \(bu 2
Add \- Send custom data field to BinAuth via auth_client method [bluewavenet]
.IP \(bu 2
Fix \- missing token value in auth_client [bluewavenet]
.IP \(bu 2
Add \- upload/download quota and rate configuration values [bluewavenet]
.IP \(bu 2
Add \- Send client token to binauth [bluewavenet]
.IP \(bu 2
Add \- Rename upload_limit and download_limit to upload_rate and download_rate [bluewavenet]
.IP \(bu 2
Fix \- Pass correct session end time to binauth [bluewavenet]
.IP \(bu 2
Add \- some debuglevel 3 messages [bluewavenet]
.IP \(bu 2
Add \- description of the favicon and page footer images [bluewavenet]
.IP \(bu 2
Add \- Authmon collect authentication parameters from fas\-aes\-https [bluewavenet]
.IP \(bu 2
Add \- sessionlength to ndsctl auth [bluewavenet]
.IP \(bu 2
Fix \- Page fault when ndsctl auth is called and client not found [bluewavenet]
.IP \(bu 2
Add \- Enable BinAuth / fas_secure_enabled level 3 compatibility [bluewavenet]
.IP \(bu 2
Fix \- Correctly set BinAuth session_end [bluewavenet]
.IP \(bu 2
Add \- Updates to Templated Splash pages [bluewavenet]
.IP \(bu 2
Add \- Community Testing files [bluewavenet]
.IP \(bu 2
Fix \- BinAuth error passing client session times [bluewavenet]
.IP \(bu 2
Fix \- PHP notice \- undefined constant [bluewavenet]
.IP \(bu 2
Fix \- OpenWrt CONFLICTS variable in Makefile [bluewavenet]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Wed, 24 Jun 2020 20:55:18 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (5.0.1)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Fix \- Path Traversal Attack vulnerability allowed by libmicrohttpd\(aqs built in unescape functionality [bluewavenet] [lynxis]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Wed, 06 May 2020 19:56:27 +0000
.UNINDENT
.UNINDENT
.sp
openNDS (5.0.0)
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Import \- from NoDogSplash 4.5.0 allowing development without compromising NoDogSplash optimisation for minimum resource utilisation [bluewavenet]
.IP \(bu 2
Rename \- from NoDogSplash to openNDS [bluewavenet]
.IP \(bu 2
Create \- openNDS avatar and splash image [bluewavenet]
.IP \(bu 2
Move \- wait_for_interface to opennds C code ensuring consistent start at boot time for all hardware, OpenWrt and Debian [bluewavenet]
.IP \(bu 2
Add \- Enable https protocol for remote FAS [bluewavenet]
.IP \(bu 2
Add \- trusted devices list to ndsctl json output [bluewavenet]
.IP \(bu 2
Add \- option unescape_callback_enabled [bluewavenet]
.IP \(bu 2
Add \- get_client_token library utility [bluewavenet]
.IP \(bu 2
Add \- utf\-8 to PreAuth header [bluewavenet]
.IP \(bu 2
Add \- PreAuth Support for hashed id (hid) if sent by NDS [bluewavenet]
.IP \(bu 2
Add \- library script shebang warning for systems not running Busybox [bluewavenet]
.IP \(bu 2
Add \- htmlentityencode function, encode gatewayname in templated splash page [bluewavenet]
.IP \(bu 2
Add \- htmlentity encode gatewayname on login page (PreAuth) [bluewavenet]
.IP \(bu 2
Add \- Simple customisation of log file location for PreAuth and BinAuth [bluewavenet]
.IP \(bu 2
Add \- option use_outdated_mhd [bluewavenet]
.IP \(bu 2
Add \- url\-encode and htmlentity\-encode gatewayname on startup [bluewavenet]
.IP \(bu 2
Add \- Allow special characters in username (PreAuth) [bluewavenet]
.IP \(bu 2
Add \- Documentation updates [bluewavenet]
.IP \(bu 2
Add \- Various style and cosmetic updates  [bluewavenet]
.IP \(bu 2
Fix \- Change library script shebang to bash in Debian [bluewavenet]
.IP \(bu 2
Fix \- Remove unnecessary characters causing script execution failure in Debian [bluewavenet]
.IP \(bu 2
Fix \- Add missing NULL parameter in MHD_OPTION_UNESCAPE_CALLBACK [skra72] [bluewavenet]
.IP \(bu 2
Fix \- Script failures running on Openwrt 19.07.0 [bluewavenet]
.IP \(bu 2
Fix \- Preauth, status=authenticated [bluewavenet]
.IP \(bu 2
Fix \- Prevent ndsctl from running if called from a Binauth script. [bluewavenet]
.IP \(bu 2
Fix \- Minor changes in Library scripts for better portability [bluewavenet]
.IP \(bu 2
Fix \- Prevent php notices on pedantic php servers [bluewavenet]
.IP \(bu 2
Fix \- broken remote image retrieval (PreAuth) [bluewavenet]
.IP \(bu 2
Fix \- Allow use of "#" in gatewayname [bluewavenet]
.UNINDENT
.UNINDENT
.UNINDENT
\(em Rob White <\fI\%dot@blue\-wave.net\fP> Sat, 03 Apr 2020 13:23:36 +0000
.UNINDENT
.UNINDENT
.SH INSTALLING OPENNDS
.SS Prerequisites
.sp
openNDS is designed to run on a device configured as an IPv4 router and will have at least two network interfaces:
.INDENT 0.0
.INDENT 3.5
\fBA WAN interface\fP (Wide Area Network). This interface must be connected to an Internet feed:
.INDENT 0.0
.IP \(bu 2
Either an ISP CPE (Internet Service Provider Customer Premises Equipment)
.IP \(bu 2
Or another router, such as the venue ADSL router.
.IP \(bu 2
It must be configured as a DHCP client, obtaining its IPv4 address and DNS server from the connected network.
.UNINDENT
.sp
\fBA LAN interface\fP (Local Area Network). This interface MUST be configured to:
.INDENT 0.0
.IP \(bu 2
Provide the Default IPv4 gateway in a private IPv4 subnet that is different to any private subnets between it and the ISP CPE
.IP \(bu 2
Provide DHCP services to connected clients
.IP \(bu 2
Provide DNS services to connected clients
.IP \(bu 2
Provide Network Address Translation (NAT) for all outgoing traffic directed to the WAN interface.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Installing on OpenWrt
.INDENT 0.0
.IP \(bu 2
Have a router working with OpenWrt. At the time of writing, openNDS has been tested with OpenWrt 18.06.x, 19.7.x and Snapshot.
.IP \(bu 2
OpenWrt version 19.07.x or less requires openNDS v5.2.0 or less.
.IP \(bu 2
OpenWrt Snapshot or versions higher than 19.07.x require openNDS v6.0.0 or higher.
.IP \(bu 2
Note: To run openNDS v6.0.0 or higher on OpenWrt 19.07.x or lower you must upgrade/install libmicrohttpd to v0.9.71 or higher first.
.IP \(bu 2
openNDS may or may not work on older versions of OpenWrt or on other kinds of Linux\-based router firmware.
.IP \(bu 2
Make sure your router is basically working before you try to install  openNDS. In particular, make sure your DHCP daemon is serving addresses on the interface that openNDS will manage.
.sp
The default interface is br\-lan but can be changed to any LAN interface by editing the /etc/config/opennds file.
.IP \(bu 2
To install openNDS, you may use the OpenWrt Luci web interface or alternatively, ssh to your router and run the command:
.INDENT 2.0
.INDENT 3.5
\fBopkg update\fP
.UNINDENT
.UNINDENT
.sp
followed by
.INDENT 2.0
.INDENT 3.5
\fBopkg install opennds\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
openNDS is enabled by default and will start automatically on reboot or can be started and stopped manually.
.IP \(bu 2
If the interface that you want openNDS to manage is not br\-lan,
edit /etc/config/opennds and set GatewayInterface.
.IP \(bu 2
To start openNDS, run the following, or just reboot the router:
.INDENT 2.0
.INDENT 3.5
\fBservice opennds start\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To test the installation, connect a client device to the interface on your router that is managed by openNDS (for example, connect to the router\(aqs wireless lan).
.UNINDENT
.INDENT 0.0
.INDENT 3.5
Most client device operating systems and browsers support Captive Portal Detection (CPD) and the operating system or browser on that device will attempt to contact a pre defined port 80 web page.
.sp
CPD will trigger openNDS to serve the default splash page where you can click or tap Continue to access the Internet.
.sp
See the Authentication section for details of setting up a proper authentication process.
.sp
If your client device does not display the splash page it most likely does not support CPD.
.sp
You should then manually trigger openNDS by trying to access a port 80 web site (for example, google.com:80 is a good choice).
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
To stop openNDS:
.INDENT 2.0
.INDENT 3.5
\fBservice opennds stop\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To uninstall openNDS:
.INDENT 2.0
.INDENT 3.5
\fBopkg remove opennds\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Generic Linux
.sp
openNDS can be compiled for most distributions of Linux
.sp
openNDS \fBrequires the libmicrohttpd (MHD) library\fP\&. The version must be greater than 0.9.51 but no higher than 0.9.70 for openNDS v5.2.0.
openNDS v6.0.0 or higher requires libmicrohttpd 0.9.71 or higher.
.sp
If your distribution of Linux has a package of version less then 0.9.69, you can set the openNDS config option \fIuse_outdated_mhd\fP to 1. This will force openNDS to use it.
.INDENT 0.0
.INDENT 3.5
Older versions of MHD convert & and + characters to spaces when present in form data.
.sp
This can make a PreAuth or BinAuth impossible to use for a client if form data contains either of these characters eg. in username or password.
.sp
MHD versions earlier than 0.9.69 are detected.
.sp
If the option \fIuse_outdated_mhd\fP is set to 0 (default), NDS will terminate if MHD is earlier than 0.9.69
.sp
If this option is set to 1, NDS will start but log an error.
.UNINDENT
.UNINDENT
.sp
You can also compile libmicrohttpd yourself to get the latest version.
.sp
To compile libmicrohttpd and openNDS, see the chapter "How to Compile and install openNDS".
.SH HOW OPENNDS (NDS) WORKS
.sp
openNDS is a Captive Portal Engine. Any Captive Portal, including NDS, will have two main components:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Something that does the capturing, and
.IP \(bu 2
Something to provide a Portal for client users to log in.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
openNDS MUST run on a device configured as an IPv4 router.
.sp
A wireless router will typically be running OpenWrt or some other Linux distribution.
.sp
A router, by definition, will have two or more interfaces, at least one to connect to the wide area network (WAN) or Internet feed, and at least one connecting to the local area network (LAN).
.sp
Each LAN interface must also act as the Default IP Gateway for its LAN, ideally with the interface serving IP addresses to client devices using DHCP.
.sp
Multiple LAN interfaces can be combined into a single bridge interface. For example, ethernet, 2.4Ghz and 5Ghz networks are typically combined into a single bridge interface. Logical interface names will be assigned such as eth0, wlan0, wlan1 etc. with the combined bridge interface named as br\-lan.
.sp
NDS will manage one or more of them of them. This will typically be br\-lan, the bridge to both the wireless and wired LAN, but could be, for example, wlan0 if you wanted NDS to work just on the wireless interface.
.SS Summary of Operation
.sp
By default, NDS blocks everything, but intercepts port 80 requests.
.sp
An initial port 80 request will be generated on a client device, usually automatically by the client device\(aqs built in Captive Portal Detection (CPD), or possibly by the user manually browsing to an http web page.
.sp
This request will of course \fBbe routed by the client device to the Default Gateway\fP of the local network. The Default Gateway will, as we have seen, be the router interface that NDS is managing.
.SS The Thing That Does the Capturing (NDS)
.INDENT 0.0
.INDENT 3.5
As soon as this initial port 80 request is received on the default gateway interface, NDS will "Capture" it, make a note of the client device identity, allocate a unique token for the client device, then redirect the client browser to the Portal component of NDS.
.UNINDENT
.UNINDENT
.SS The Thing That Provides the Portal (FAS or PreAuth)
.INDENT 0.0
.INDENT 3.5
The client browser is redirected to the Portal component. This is a web service that is configured to know how to communicate with the core engine of NDS.
.sp
This is commonly known as the Splash Page.
.sp
NDS has its own web server built in and this can be used to serve the Portal "Splash" pages to the client browser, or a separate web server can be used.
.sp
openNDS comes with two standard Splash Page options pre\-installed.
.sp
One provides a trivial Click to Continue splash page and the other provides a Client User form requiring Name and Email address to be entered.
.sp
Both of these can be customised or a complete specialised Portal can be written by the installer (See FAS, PreAuth).
.sp
FAS, or Forward Authentication Service may use the web server embedded in NDS, a separate web server installed on the NDS router, a web server residing on the local network or an Internet hosted web server.
.sp
The user of the client device will always be expected to complete some actions on the splash page.
.sp
Once the user on the client device has successfully completed the splash page actions, that page then links directly back to NDS.
.sp
For security, NDS expects to receive the same valid token it allocated when the client issued its initial port 80 request. If the token received is valid, NDS then "authenticates" the client device, allowing access to the Internet.
.sp
Post authentication processing extensions may be added to NDS (See BinAuth). Once NDS has received a valid token it calls a BinAuth script.
.sp
If the BinAuth script returns positively (ie return code 0), NDS then "authenticates" the client device, allowing access to the Internet.
.sp
Where FAS is used, secure modes are provided (levels 1, 2 and 3), where the client token and other required variables are kept securely hidden from the Client, ensuring verification cannot be bypassed.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
FAS and Binauth can be enabled together. This can give great flexibility, with FAS providing remote verification and Binauth providing local post authentication processing closely linked to  NDS.
.UNINDENT
.UNINDENT
.SS Captive Portal Detection (CPD)
.sp
All modern mobile devices, most desktop operating systems and most browsers now have a CPD process that automatically issues a port 80 request on connection to a network. NDS detects this and serves a special “splash” web page to the connecting client device.
.sp
The port 80 html request made by the client CPD can be one of many vendor specific URLs.
.INDENT 0.0
.INDENT 3.5
Typical CPD URLs used are, for example:
.INDENT 0.0
.IP \(bu 2
\fIhttp://captive.apple.com/hotspot\-detect.html\fP
.IP \(bu 2
\fIhttp://connectivitycheck.gstatic.com/generate_204\fP
.IP \(bu 2
\fIhttp://connectivitycheck.platform.hicloud.com/generate_204\fP
.IP \(bu 2
\fIhttp://www.samsung.com/\fP
.IP \(bu 2
\fIhttp://detectportal.firefox.com/success.txt\fP
.IP \(bu 2
Plus many more
.UNINDENT
.UNINDENT
.UNINDENT
.sp
It is important to remember that CPD is designed primarily for mobile devices to automatically detect the presence of a portal and to trigger the login page, without having to resort to breaking SSL/TLS security by requiring the portal to redirect port 443 for example.
.sp
Just about all current CPD implementations work very well but some compromises are necessary depending on the application.
.sp
The vast majority of devices attaching to a typical Captive Portal are mobile devices. CPD works well giving the initial login page.
.sp
For a typical guest wifi, eg a coffee shop, bar, club, hotel etc., a device connects, the Internet is accessed for a while, then the user takes the device out of range.
.sp
When taken out of range, a typical mobile device begins periodically polling the wireless spectrum for SSIDs that it knows about to try to obtain a connection again, subject to timeouts to preserve battery life.
.sp
Most Captive Portals have a session duration limit (NDS included).
.sp
If a previously logged in device returns to within the coverage of the portal, the previously used SSID is recognised and CPD is triggered and tests for an Internet connection in the normal way. Within the session duration limit of the portal, the Internet connection will be established, if the session has expired, the splash page will be displayed again.
.sp
Early mobile device implementations of CPD used to poll their detection URL at regular intervals, typically around 30 to 300 seconds. This would trigger the Portal splash page quite quickly if the device stayed in range and the session limit had been reached.
.sp
However it was very quickly realised that this polling kept the WiFi on the device enabled continuously having a very negative effect on battery life, so this polling whilst connected was either increased to a very long interval or removed all together (depending on vendor) to preserve battery charge. As most mobile devices come and go into and out of range, this is not an issue.
.sp
A common issue raised is:
.sp
\fIMy devices show the splash page when they first connect, but when the authorization expires, they just announce there is no internet connection. I have to make them "forget" the wireless network to see the splash page again. Is this how is it supposed to work?\fP
.sp
The workaround is as described in the issue, or even just manually disconnecting or turning WiFi off and on will simulate a "going out of range", initialising an immediate trigger of the CPD. One or any combination of these workarounds should work, again depending on the particular vendor\(aqs implementation of CPD.
.sp
In contrast, most laptop/desktop operating systems, and browser versions for these still implement CPD polling whilst online as battery considerations are not so important.
.sp
For example, Gnome desktop has its own built in CPD browser with a default interval of 300 seconds. Firefox also defaults to something like 300 seconds. Windows 10 is similar.
.sp
This IS how it is supposed to work, but does involve some compromises.
.sp
The best solution is to set the session timeout to a value greater than the expected length of time a client device is likely to be present. Experience shows a limit of 24 hours covers most situations eg bars, clubs, coffee shops, motels etc. If for example an hotel has guests regularly staying for a few days, then increase the session timeout as required.
.sp
Staff at the venue could have their devices added to the Trusted List if appropriate, but experience shows, it is better not to do this as they very soon learn what to do and can help guests who encounter the issue. (Anything that reduces support calls is good!)
.SS Network Zone Detection (Where is the Client Connected?)
.sp
Client devices can be connected to one of a number of local WiFi SSIDs, connected directly or indirectly by ethernet, or connected via a wireless mesh network. Each connection type available is considered as a Network Zone.
.sp
NDS detects which zone each client is connected to. This information can be used to dynamically customise the login for each zone.
.sp
For example a coffee shop might have two SSIDs configured:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Staff (Secure SSID ie with access code)
.IP \(bu 2
Customers (open SSID with login form)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In this example SSID "Staff" is configured on interface wlan0, and considered as Zone "Private".
.sp
However, SSID "Customers" is configured on virtual interface wlan0\-1, and considered as Zone "Public".
.sp
NDS detects which zone is being used by a client and a relevant login page can be served.
.SS Packet filtering
.sp
openNDS considers four kinds of packets coming into the router over the managed interface. Each packet is one of these kinds:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
\fBBlocked\fP, if the MAC mechanism is block, and the source MAC address of the packet matches one listed in the BlockedMACList; or if the MAC mechanism is allow, and source MAC address of the packet does not match one listed in the AllowedMACList or the TrustedMACList. These packets are dropped.
.IP 2. 3
\fBTrusted\fP, if the source MAC address of the packet matches one listed in the TrustedMACList. By default, these packets are accepted and routed to all destination addresses and ports. If desired, this behavior can be customized by FirewallRuleSet trusted\-users and FirewallRuleSet trusted\-users\-to\-router lists in the opennds.conf configuration file, or by the EmptyRuleSetPolicy trusted\-users EmptyRuleSetPolicy trusted\-users\-to\-router directives.
.IP 3. 3
\fBAuthenticated\fP, if the packet\(aqs IP and MAC source addresses have gone through the openNDS authentication process and has not yet expired. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet authenticated\-users and FirewallRuleSet users\-to\-router in the opennds.conf configuration file).
.IP 4. 3
\fBPreauthenticated\fP\&. Any other packet. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet      preauthenticated\-users and FirewallRuleSet users\-to\-router in the opennds.conf configuration file). Any other packet is dropped, except that a packet for destination port 80 at any address is redirected to port 2050 on the router, where openNDS\(aqs built in libhttpd\-based web server is listening. This begins the \(aqauthentication\(aq process. The server will serve a splash page back to the source IP address of the packet. The user clicking the appropriate link on the splash page will complete the process, causing future packets from this IP/MAC address to be marked as Authenticated until the inactive or forced timeout is reached, and its packets revert to being Preauthenticated.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
openNDS implements these actions by inserting rules in the router\(aqs iptables mangle PREROUTING chain to mark packets, and by inserting rules in the nat PREROUTING, filter INPUT and filter FORWARD chains which match on those marks.
.sp
Because it inserts its rules at the beginning of existing chains, openNDS should be insensitive to most typical existing firewall configurations.
.SS Data volume and Rate Quotas
.sp
openNDS (NDS) has built in \fIData Volume\fP and \fIData Rate\fP quota support.
.sp
Data volume and data rate quotas can be set globally in the config file.
.sp
The global values can be overridden on a client by client basis as required.
.SS Traffic Shaping
.sp
openNDS (NDS) supports Traffic Shaping (Bandwidth Limiting) using the SQM \- Smart Queue Management (sqm\-scripts) package, available for OpenWrt and generic Linux.
.SH THE SPLASH PAGE
.sp
As you will see mentioned in the "How openNDS (NDS) Works" section, an initial port 80 request is generated on a client device, either by the user manually browsing to an http web page, or, more usually, automatically by the client device\(aqs built in Captive Portal Detection (CPD).
.sp
This request is intercepted by NDS and an html Splash Page is served to the user of the client device to enable them to authenticate and be granted Internet access.
.SS Types of Splash Page
.sp
This Splash page can be one of the following:
.SS A Dynamic Web Page served by the built in openNDS web server
.INDENT 0.0
.INDENT 3.5
A script or executable file is called by openNDS. This script or executable will generate html code for the openNDS web server.
.sp
In openNDS this is called "PreAuth", as openNDS itself serves the splash page as a PRElude to AUTHentication.
.sp
Simple coding in the script enables a dialogue with the client user, for dissemination of information, user response and authentication.
.sp
This is an implementation of Forward Authentication Services \fB(FAS)\fP, \fIwithout the resource utilisation of a separate web server\fP, particularly useful for legacy devices with limited flash and RAM capacity.
.UNINDENT
.UNINDENT
.SS A Dynamic Web Page served by an independent web server
.INDENT 0.0
.INDENT 3.5
This independent web server can be on the same device as openNDS, on the same Local Area Network as NDS, or on External Web Hosting Services.
.sp
A script or executable file is called by openNDS on the independent web server.
.sp
This has the advantage having the full flexibility of using readily available mainstream web servers, located anywhere, enabling full flexibility in design and implementation of the captive portal functionality, ranging from a self contained system through to a fully integrated multi site system with a common database.
.UNINDENT
.UNINDENT
.SS The Pre\-Installed Basic Splash Pages
.INDENT 0.0
.INDENT 3.5
By default, the Splash pages consist of a simple click to continue dialogue followed by a Welcome or advertising page. A simple config option allows you to select instead a Name/EmailAddress login dialogue.
.sp
In many instances, one or other of these simple methods will be all that is required, but the power of FAS, PreAuth and BinAuth can be used to create very sophisticated Captive Portal Systems.
.UNINDENT
.UNINDENT
.SS The Legacy splash.html Static Web Page
.sp
The legacy static splash.html page is now deprecated and disabled. It will be removed in later releases.
It can be re\-enabled in this release allowing time for migration to the new openNDS API. This is achieved by setting the allow_legacy_splash option in the config file.
.SS Displaying Remote Content
.SS openNDS provides a simple means of displaying remote content
.INDENT 0.0
.INDENT 3.5
openNDS can display content from third party web hosting, on the client user login screen.
.sp
This is ideal for serving information, banner advertising etc. when the openNDS device has very limited resources.
.sp
An example is described in the \fBDisplaying Remote Banner Images\fP section of the PreAuth chapter.
.UNINDENT
.UNINDENT
.SS openNDS has built in Walled Garden support
.INDENT 0.0
.INDENT 3.5
Sophisticated remote content can be served, with access controlled by the openNDS Walled Garden. Simple configuration options can enable such things as a Paypal payment system or access to Facebook resources.
.sp
For details see the Walled Garden Section.
.UNINDENT
.UNINDENT
.SH THE CLIENT STATUS PAGE
.sp
From version 8.0.0 onwards, openNDS has a Client Status Page.
.sp
This page is accessible by any connected client by accessing the default url:
.sp
\fI\%http://status.client\fP
.sp
If the client has been authenticated in the normal way by the client CPD process, a page displaying the Gatewayname and the Network Zone the client device is currently using. A list of allowed quotas and current usage is displayed along with "Refresh" and "Logout" buttons.
.sp
If the client has not been authenticated, or has been deauthenticated due to timeout or quota usage, then a "Network Authentication Required" page is displayed with "Refresh" and "Portal Login"
.sp
The "Portal Login" button allows the client to immediately attempt to login without waiting for the client CPD to trigger.
.sp
The URL used to access this page can be changed by setting the config option gatewayfqdn
.sp
For best results it is recommended that gatewayfqdn is set to two words separated by a single period eg in OpenWrt:
.INDENT 0.0
.INDENT 3.5
\fIoption gatewayfqdn \(aqmy.status\(aq\fP
.UNINDENT
.UNINDENT
.SH CUSTOM PARAMETERS
.sp
Custom Parameters were first introduced in openNDS version 7.
.sp
Custom parameters are defined in the config file and are sent as fixed values to FAS in the encoded/encrypted query string where they can be parsed and used by the FAS.
.sp
This is particularly useful in a remote or centralised FAS that is serving numerous instances of openNDS at different locations/venues.
.INDENT 0.0
.IP \(bu 2
Custom Parameters are listed in configuration file in the form of "param_name=param_value"
.IP \(bu 2
param_name and param_value must be htmlentity encoded if containing white space or single quotes.
.UNINDENT
.sp
For example in the OpenWrt UCI config file:
.sp
\fBlist fas_custom_parameters_list \(aq<param_name1=param_value1> <param_name2=param_value2> [.....] <param_nameN=param_valueN>\(aq\fP
.sp
A real example might be:
.sp
\fBlist fas_custom_parameters_list \(aqlocation=main_building admin_email=norman@bates\-motel.com>\(aq\fP
.SH FORWARDING AUTHENTICATION SERVICE (FAS)
.SS Overview
.sp
openNDS (NDS) has the ability to forward requests to a third party authentication service (FAS). This is enabled via simple configuration options.
.INDENT 0.0
.TP
.B These options are:
.INDENT 7.0
.IP 1. 3
\fBfasport\fP\&. This enables Forwarding Authentication Service (FAS). Redirection is changed from the default login.sh to a separate FAS. The value is the IP port number of the FAS.
.IP 2. 3
\fBfasremoteip\fP\&. If set, this is the remote ip address of the FAS, if not set it will take the value of the NDS gateway address.
.IP 3. 3
\fBfasremotefqdn\fP If set, this is the remote fully qualified domain name (FQDN) of the FAS
.IP 4. 3
\fBfaspath\fP\&. This is the path from the FAS Web Root (not the file system root) to the FAS login page.
.IP 5. 3
\fBfas_secure_enable\fP\&. This can have four values, "0", "1", "2" or "3" providing different levels of security.
.IP 6. 3
\fBfaskey\fP Used in combination with fas_secure_enable level 1, 2 and 3, this is a key phrase for NDS to encrypt data sent to FAS.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
FAS (and Preauth/FAS) enables pre authentication processing. NDS authentication is the process that openNDS uses to allow a client device to access the Internet through the Firewall. In contrast, Forward Authentication is a process of "Credential Verification", after which FAS, if the verification process is successful, passes the client token to NDS for access to the Internet to be granted.
.UNINDENT
.UNINDENT
.SS Using FAS
.sp
\fBNote\fP:
All addresses (with the exception of fasremoteip) are relative to the \fIclient\fP device, even if the FAS is located remotely.
.sp
When FAS is enabled, openNDS automatically configures firewall access to the FAS service.
.sp
The FAS service must serve a splash page of its own to replace the openNDS served output of the default login.sh script. For fas_secure_enable "0", "1", and "2" this is enforced as http. For fas_secure_enable level "3", it is enforced as https.
.sp
Typically, the FAS service will be written in PHP or any other language that can provide dynamic web content.
.sp
FAS can then provide an action form for the client, typically requesting login, or self account creation for login.
.sp
The FAS can be on the same device as openNDS, on the same local area network as NDS, or on an Internet hosted web server.
.SS Security
.sp
\fBIf FAS Secure is enabled\fP (Levels 1 (default), 2 and 3), the client authentication token is kept secret at all times. Instead, faskey is used to generate a hashed id value (hid) and this is sent by openNDS to the FAS. The FAS must then in turn generate a new return hash id (rhid) to return to openNDS in its authentication request.
.INDENT 0.0
.INDENT 3.5
\fBIf set to "0"\fP The FAS is enforced by NDS to use \fBhttp\fP protocol.
The client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir. This method is easy to bypass and useful only for the simplest systems where security does not matter.
.sp
\fBIf set to "1"\fP The FAS is enforced by NDS to use \fBhttp\fP protocol.
A base64 encoded query string containing the hid is sent to the FAS, along with the clientip, clientmac, gatewayname, client_hid, gatewayaddress, authdir, originurl, clientif and custom parameters and variables.
.sp
Should sha256sum not be available, then openNDS will terminate with an error message on startup.
.sp
\fBIf set to "2"\fP The FAS is enforced by NDS to use \fBhttp\fP protocol.
.sp
clientip, clientmac, gatewayname, client_hid, gatewayaddress, authdir, originurl and clientif are encrypted using faskey and passed to FAS in the query string.
.sp
The query string will also contain a randomly generated initialization vector to be used by the FAS for decryption.
.sp
The cipher used is "AES\-256\-CBC".
.sp
The "php\-cli" package and the "php\-openssl" module must both be installed for fas_secure level 2.
.sp
openNDS does not depend on this package and module, but will exit gracefully if this package and module are not installed when this level is set.
.sp
The FAS must use the query string passed initialisation vector and the pre shared fas_key to decrypt the query string. An example FAS level 2 php script (fas\-aes.php) is stored in the /etc/opennds directory and also supplied in the source code. This should be copied the the web root of a suitable web server for use.
.sp
\fBIf set to "3"\fP The FAS is enforced by openNDS to use \fBhttps\fP protocol.
Level 3 is the same as level 2 except the use of https protocol is enforced for FAS. In addition, the "authmon" daemon is loaded. This allows the external FAS, after client verification, to effectively traverse inbound firewalls and address translation to achieve NDS authentication without generating browser security warnings or errors. An example FAS level 3 php script (fas\-aes\-https.php) is pre\-installed in the /etc/opennds directory and also supplied in the source code. This should be copied the the web root of a suitable web server for use.
.sp
\fBOption faskey has a default value.\fP It is recommended that this is set to some secret value in the config file and the FAS script set to use a matching value, ie faskey must be pre\-shared with FAS.
.UNINDENT
.UNINDENT
.SS Example FAS Query strings
.INDENT 0.0
.INDENT 3.5
\fBLevel 0\fP (fas_secure_enabled = 0)
.INDENT 0.0
.INDENT 3.5
NDS sends the token and other information to FAS as clear text.
.sp
\fIhttp://fasremoteip:fasport/faspath?authaction=http://gatewayaddress:gatewayport/opennds_auth/?clientip=[clientip]&gatewayname=[gatewayname]&tok=[token]&redir=[requested_url]\fP
.sp
Note: a knowledgeable user could bypass FAS, so running fas_secure_enabled at level 1, 2 or 3 is recommended.
.UNINDENT
.UNINDENT
.sp
\fBLevel 1\fP (fas_secure_enabled = 1)
.INDENT 0.0
.INDENT 3.5
NDS sends a query string containing a base64 encoded string containing required parameters and variables, plus any FAS variables generated in the client dialogue, such as username and email address. The client token is never exposed.
.sp
Example Level 1 query string:
.INDENT 0.0
.INDENT 3.5
\fIhttp://fasremotefqdn:fasport/faspath?fas=[b64encodedstring]&username=[client_username]&emailaddr=[client_email]\fP
.UNINDENT
.UNINDENT
.sp
The b64encoded string will contain a comma space separated list of parameters.
.sp
The decoded string received by FAS will be of the form:
.sp
\fI[varname1]=[var1], [varname2]=[var2], ..... etc\fP (the separator being comma\-space).
.UNINDENT
.UNINDENT
.sp
For example:
.INDENT 0.0
.INDENT 3.5
\fIclientip=[clientipaddress], clientmac=[clientmacaddress], gatewayname=[gatewayname], client token, gatewayaddress, authdir, originurl\fP
.UNINDENT
.UNINDENT
.sp
The FAS must return the hash of the concatenated hid value and the value of faskey identified in the query string as "tok". NDS will automatically detect this.
.sp
\fBLevels 2 and 3\fP (fas_secure_enabled = 2 and fas_secure_enabled = 3), openNDS sends encrypted information to FAS.
.sp
\fIhttp://fasremotefqdn:fasport/faspath?fas=[aes\-256\-cbc data]&iv=[random initialisation vector]\fP (level 2)
.sp
\fIhttps://fasremotefqdn:fasport/faspath?fas=[aes\-256\-cbc data]&iv=[random initialisation vector]\fP (level 3)
.INDENT 0.0
.INDENT 3.5
It is the responsibility of FAS to decrypt the aes\-256\-cbc data it receives, using the pre shared faskey and the random initialisation vector.
.UNINDENT
.UNINDENT
.sp
The decrypted string received by FAS will be of the form:
[varname1]=[var1], [varname2]=[var2], ..... etc. (the separator being comma\-space).
.sp
For example:
.INDENT 0.0
.INDENT 3.5
\fIclientip=[clientipaddress], clientmac=[clientmacaddress], gatewayname=[gatewayname], client token, gatewayaddress, authdir, originurl\fP
.UNINDENT
.UNINDENT
.sp
It is the responsibility of FAS to parse the decrypted string for the variables it requires.
.UNINDENT
.UNINDENT
.SS Example scripts
.sp
Full details of how to use FAS query strings can be seen in the example scripts, login.sh, fas\-hid.php, fas\-aes.php and fas\-aes\-https.php
.SS Custom Parameters
.sp
Custom Parameters are primarily intended to be used by remote configuration tools and are generally useful for passing static information to a remote FAS.
.sp
A list of Custom Parameters can be defined in the configuration file.
Once a custom parameter is defined in the configuration, its value will be fixed.
.sp
Parameters must be of the form param_name=param_value and may not contain white space or single quote characters.
.sp
Custom parameters are added to the base64 encoded query string when FAS level 1 is set or the basic login option is used. Note the basic login option is a special case of FAS level 1 running the login.sh script.
.sp
Custom parameters are added to the encrypted query string when FAS levels 1, 2 and 3 are set.
.sp
The fas_custom_parameters_list option in the configuration file is used to set custom parameters. This is detailed in the default configuration file.
.sp
It is the responsibility of FAS to parse the query string for the custom parameters it requires.
.SS Network Zones \- Determining the Interface the Client is Connected To
.sp
The Network coverage of a Captive Portal can take many forms, from a single SSID through to an extensive mesh network.
.sp
Using FAS, it is quite simple to dynamically adapt the Client Login page depending on the Network Zone a client is connected to.
NDS can determine the local interface or 802.11s mesh network node a client is using. A simple lookup table can then be included in a custom FAS, relating interfaces or mesh nodes to sensibly named coverage zones.
.sp
A very simple example would be a captive portal set up with a wireless network for "Staff", another for "Guests" and office machines connected via ethernet.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Ethernet connected office machines would gain access by simply clicking "Continue".
.IP \(bu 2
Staff mobiles connect to the Staff WiFi using a standard access code then clicking "Continue".
.IP \(bu 2
Guests connect to the open Guest Wifi and are required to enter details such as Name, email address etc.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
NDS is aware of the interface or mesh node a client is using.
.sp
For a FAS using \fIfas_secure_enabled = 2\fP, an additional variable, clientif, is sent to the FAS in the encrypted query string (local or remote FAS).
.sp
For all other levels of fas_secure_enabled, PreAuth and BinAuth, the library utility "get_client_interface" is required to be used by the relevant script (local FAS only).
.sp
Working examples can be found in the included scripts:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
fas\-aes.php
.IP \(bu 2
login.sh
.IP \(bu 2
demo\-preauth.sh
.IP \(bu 2
demo\-preauth\-remote\-image.sh
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For details of the clientif variable and how to use get_client_interface, see the section \fBLibrary Utilities\fP\&.
.SS After Successful Verification by FAS
.sp
If the client is successfully verified by the FAS, FAS will send the return hash id (rhid) to openNDS to finally allow the client access to the Internet.
.SS Post FAS processing
.sp
Once the client has been authenticated by the FAS, NDS must then be informed to allow the client to have access to the Internet.
.sp
The method of achieving this depends upon the fas_secure_enabled level.
.SS Authentication Method for fas_secure_enabled levels 0,1 and 2
.INDENT 0.0
.INDENT 3.5
Once FAS has verified the client credentials, authentication is achieved by accessing NDS at a special virtual URL.
.sp
This virtual URL is of the form:
.sp
\fIhttp://[nds_ip]:[nds_port]/[authdir]/?tok=[token]&redir=[landing_page_url]\fP
.sp
This is most commonly achieved using an html form of method GET.
The parameter redir can be the client\(aqs originally requested URL sent by NDS, or more usefully, the URL of a suitable landing page.
.UNINDENT
.UNINDENT
.SS The "login_option" special case
.sp
The default "login_option" script, login.sh, must always be a local script so has access to ndsctl auth method of authentication without needing the authmon daemon so uses this rather than use the authdir GET method detailed above. This means login.sh can directly set client quotas without requiring BinAuth.
.SS Authentication Method for fas_secure_enabled level 3 (Authmon Daemon)
.INDENT 0.0
.INDENT 3.5
When fas_secure_enabled level 3 is used (https protocol), post verification authentication is achieved by the openNDS Authmon daemon.
.sp
Authmon is started by openNDS to facilitate NAT traversal and allow a remote https FAS to communicate with the local openNDS.
.sp
FAS will deposit client authentication variables for the Authmon daemon to use for the authentication process. These variables are as follows:
.INDENT 0.0
.IP \(bu 2
clientip: The ip address of the client to be authenticated
.IP \(bu 2
sessionlength: length of session \- minutes
.IP \(bu 2
uploadrate: maximum allowed upload data rate \- kbits/sec
.IP \(bu 2
downloadrate: maximum allowed download data rate \- kbits/sec
.IP \(bu 2
uploadquota: allowed upload data quota \- kBytes
.IP \(bu 2
downloadquota: allowed download data quota \- kBytes
.IP \(bu 2
custom: A custom data string that will be sent to BinAuth
.UNINDENT
.sp
Details can be found in the example script fas\-aes\-https.php
.UNINDENT
.UNINDENT
.sp
Be aware that many client CPD processes will \fBautomatically close\fP the landing page as soon as Internet access is detected.
.SS BinAuth Post FAS Processing
.sp
As BinAuth can be enabled at the same time as FAS, a BinAuth script may be used for custom post FAS processing. (see BinAuth).
.sp
The example BinAuth script, binauth_log.sh, is designed to locally log details of each client authentication and receives client data including the token, ipaddress and macaddress. In addition it receives the custom data string sent from FAS.
.SS Manual Access of NDS Virtual URL
.sp
If the user of an already authenticated client device manually accesses the NDS Virtual URL, they will be redirected back to FAS with the "status" query string.
.INDENT 0.0
.INDENT 3.5
This will be of the form:
.sp
\fIhttp://fasremoteip:fasport/faspath?clientip=[clientip]&gatewayname=[gatewayname]&status=authenticated\fP
.UNINDENT
.UNINDENT
.sp
FAS should then serve a suitable error page informing the client user that they are already logged in.
.SS Running FAS on your openNDS router
.sp
FAS has been tested using uhttpd, lighttpd, ngnix, apache and libmicrohttpd.
.sp
\fBRunning on OpenWrt with uhttpd/PHP\fP:
.INDENT 0.0
.INDENT 3.5
A FAS service may run quite well on uhttpd (the web server that serves Luci) on an OpenWrt supported device with 8MB flash and 32MB ram but shortage of ram will be an issue if more than two or three clients log in at the same time.
.sp
For this reason a device with a \fBminimum\fP of 8MB flash and 64MB ram is recommended.
.UNINDENT
.UNINDENT
.sp
A device with 16MB flash or greater and 128MB ram or greater is recommended as a target for serious development.
.INDENT 0.0
.INDENT 3.5
\fIAlthough port 80 is the default for uhttpd, it is reserved for Captive Portal Detection so cannot be used for FAS. uhttpd can however be configured to operate on more than one port.\fP
.sp
We will use port 2080 in this example.
.sp
Install the module php7\-cgi. Further modules may be required depending on your requirements.
.sp
To enable FAS with php in uhttpd you must add the lines:
.INDENT 0.0
.INDENT 3.5
\fBlist listen_http    0.0.0.0:2080\fP
.sp
\fBlist interpreter ".php=/usr/bin/php\-cgi"\fP
.UNINDENT
.UNINDENT
.sp
to the /etc/config/uhttpd file in the config uhttpd \(aqmain\(aq or first section.
.sp
The two important NDS options to set will be:
.INDENT 0.0
.IP 1. 3
fasport. We will use port 2080 for uhttpd
.IP 2. 3
faspath. Set to, for example, /myfas/fas.php,
your FAS files being placed in /www/myfas/
.UNINDENT
.UNINDENT
.UNINDENT
.SS Using a Shared Hosting Server for a Remote FAS
.INDENT 0.0
.INDENT 3.5
A typical Internet hosted \fBshared\fP server will be set up to serve multiple domain names.
.sp
To access yours, it is important to configure the two options:
.INDENT 0.0
.INDENT 3.5
fasremoteip = the \fBip address\fP of the remote server
.sp
\fBAND\fP
.sp
fasremotefqdn = the \fBFully Qualified Domain name\fP of the remote server
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Using the FAS Example Scripts (fas\-hid, fas\-aes.php and fas\-aes\-https.php)
.sp
These three, fully functional, example FAS scripts are included in the package install and can be found in the /etc/opennds folder. To function, they need to be copied to the web root or a folder in the web root of your FAS http/php server.
.SS fas\-hid.php
.sp
\fBYou can run the FAS example script, fas\-hid.php\fP, locally on the same device that is running NDS, or remotely on an Internet based FAS server.
.sp
The use of http protocol is enforced. fas\-hid is specifically targeted at local systems with insufficient resources to run PHP services, yet facilitate remote FAS support without exposing the client token or requiring the remote FAS to somehow access the local ndsctl.
.sp
\fBIf run locally on the NDS device\fP, a minimum of 64MB of ram may be sufficient, but 128MB or more is recommended.
.sp
\fBIf run on a remote FAS server\fP, a minimum of 32MB of ram on the local device may be sufficient, but 64MB or more is recommended.
.SS fas\-aes.php
.sp
\fBYou can run the FAS example script, fas\-aes.php\fP, locally on the same device that is running NDS (A minimum of 64MB of ram may be sufficient, but 128MB is recommended), or remotely on an Internet based FAS server. The use of http protocol is enforced.
.SS fas\-aes\-https.php
.sp
\fBYou can run the FAS example script, fas\-aes\-https.php\fP, remotely on an Internet based https FAS server. The use of https protocol is enforced.
.sp
On the openNDS device, a minimum of 64MB of ram may be sufficient, but 128MB is recommended.
.SS Example Script File fas\-aes.php
.sp
Http protocol is enforced.
.sp
Assuming you have installed your web server of choice, configured it for port 2080 and added PHP support using the package php7\-cgi, you can do the following.
.INDENT 0.0
.INDENT 3.5
(Under other operating systems you may need to edit the opennds.conf file in /etc/opennds instead, but the process is very similar.)
.INDENT 0.0
.IP \(bu 2
Install the packages php7\-cli and php7\-mod\-openssl
.IP \(bu 2
Create a folder for the FAS script eg: /[server\-web\-root]/nds/ on the Internet FAS server
.IP \(bu 2
Place the file fas\-aes.php in /[server\-web\-root]/nds/
.sp
(You can find it in the /etc/opennds directory.)
.IP \(bu 2
Edit the file /etc/config/opennds
.UNINDENT
.INDENT 0.0
.INDENT 3.5
adding the lines:
.INDENT 0.0
.INDENT 3.5
\fBoption fasport \(aq2080\(aq\fP
.sp
\fBoption faspath \(aq/nds/fas\-aes.php\(aq\fP
.sp
\fBoption fas_secure_enabled \(aq2\(aq\fP
.sp
\fBoption faskey \(aq1234567890\(aq\fP
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Restart NDS using the command \fBservice opennds restart\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Example Script File fas\-aes\-https.php
.sp
Https protocol is enforced.
.sp
Assuming you have access to an Internet based https web server you can do the following.
.INDENT 0.0
.INDENT 3.5
(Under other operating systems you may need to edit the opennds.conf file in /etc/opennds instead, but the process is very similar.)
.INDENT 0.0
.IP \(bu 2
Install the packages php7\-cli and php7\-mod\-openssl on your NDS router
.IP \(bu 2
Create a folder for the FAS script eg: /[server\-web\-root]/nds/ on the Internet FAS server
.IP \(bu 2
Place the file fas\-aes.php in /[server\-web\-root]/nds/
.sp
(You can find it in the /etc/opennds directory.)
.IP \(bu 2
Edit the file /etc/config/opennds
.UNINDENT
.INDENT 0.0
.INDENT 3.5
adding the lines:
.INDENT 0.0
.INDENT 3.5
\fBoption fasport \(aq443\(aq\fP (or the actual port in use if different)
.sp
\fBoption faspath \(aq/nds/fas\-aes\-https.php\(aq\fP
.sp
\fBoption fas_secure_enabled \(aq3\(aq\fP
.sp
\fBoption faskey \(aq1234567890\(aq\fP
.sp
\fBoption fasremoteip \(aq46.32.240.41\(aq\fP (change this to the actual ip address of the remote server)
.sp
\fBoption fasremotefqdn \(aqblue\-wave.net\(aq\fP (change this to the actual FQDN of the remote server)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Restart NDS using the command \fBservice opennds restart\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Example Script File fas\-hid.php
.sp
Http protocol is enforced.
.sp
fas\-hid.php can be configured to be run locally or remotely in the same basic way as fas\-aes.
.sp
However it is targeted for use on devices with limited resources as it does not require openNDS to have locally installed php\-cli modules.
.sp
It uses fas_secure_enabled level 1, but sends a digest of the client token to the remote FAS. The digest is created using faskey, so the client token is not exposed.
.sp
The fas\-hid.php script then uses this digest along with the pre shared faskey to request authentication by openNDS, thus mitigating any requirement for remotely accessing ndsctl that otherwise would be required.
.sp
Assuming you have access to an Internet based http web server you can do the following.
.INDENT 0.0
.INDENT 3.5
(Under other operating systems you may need to edit the opennds.conf file in /etc/opennds instead, but the process is very similar.)
.INDENT 0.0
.IP \(bu 2
Create a folder for the FAS script eg: /[server\-web\-root]/nds/ on the Internet FAS server
.IP \(bu 2
Place the file fas\-hid.php in /[server\-web\-root]/nds/
.sp
(You can find it in the /etc/opennds directory.)
.IP \(bu 2
Edit the file /etc/config/opennds
.UNINDENT
.INDENT 0.0
.INDENT 3.5
adding the lines:
.INDENT 0.0
.INDENT 3.5
\fBoption fasport \(aq80\(aq\fP (or the actual port in use if different)
.sp
\fBoption faspath \(aq/nds/fas\-hid.php\(aq\fP
.sp
\fBoption fas_secure_enabled \(aq1\(aq\fP
.sp
\fBoption faskey \(aq1234567890\(aq\fP
.sp
\fBoption fasremoteip \(aq46.32.240.41\(aq\fP (change this to the actual ip address of the remote server)
.sp
\fBoption fasremotefqdn \(aqblue\-wave.net\(aq\fP (change this to the actual FQDN of the remote server)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Restart NDS using the command \fBservice opennds restart\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Changing faskey
.sp
The value of option faskey should of course be changed, but must also be pre\-shared with FAS by editing the example or your own script to match the new value.
.SH PREAUTH OPTION
.SS Overview
.sp
\fBPreAuth\fP is an implementation of FAS \fIwithout the resource utilisation of a separate web server\fP, particularly useful for legacy devices with limited flash and RAM capacity.
.sp
\fBPreAuth\fP is a pre\-authentication process that enables NDS to directly serve dynamic web content generated by a script or executable program.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
A PreAuth login script is pre\-installed. From version 7.0.0 onwards, this generates by default a simple "Click to Continue" page, or by setting config option login_option_enabled to "1" it generates a username/email address dialogue. No other configuration is necessary.
.UNINDENT
.UNINDENT
.sp
\fBA custom PreAuth can be enabled\fP by configuring NDS FAS to point to a virtual URL in the NDS web root instead of an independent FAS server. The location of the PreAuth script or program is provided in the config file.
.sp
\fBThe PreAuth script\fP can be a shell script or any other script type that an interpreter is available for (for example, PHP\-cli, Python etc.).
.sp
The default script is a shell script can be found at at /usr/lib/opennds/login.sh
.sp
A PreAuth program could be, for example, a compiled program written in C or any other language that has a compiler available for the platform.
.sp
The PreAuth script or program will parse the url encoded command line (query string) passed to it and output html depending on the contents of the query string it receives from NDS. In turn, NDS will serve this html to the client device that is attempting to access the Internet.
.SS Configuring a Custom PreAuth
.sp
A custom PreAuth is set up using the standard NDS configuration for FAS
(See the \fBForwarding Authentication Service (FAS)\fP section of this documentation).
.sp
In addition a single PreAuth configuration option is required to inform NDS of the location of the PreAuth script or program.
.INDENT 0.0
.TP
.B In summary, the following configuration options should be set:
.INDENT 7.0
.IP 1. 3
\fBfasport\fP\&. This enables FAS and \fImust\fP be set to the same value as the gateway port.
.IP 2. 3
\fBfaspath\fP\&. This \fImust\fP be set to the PreAuth virtual url, "/opennds_preauth/" by default.
.IP 3. 3
\fBpreauth\fP\&. This the path to the PreAuth script.
.UNINDENT
.UNINDENT
.sp
The remaining FAS configuration options must be left unset at the default values.
.INDENT 0.0
.TP
.B ie:
.INDENT 7.0
.IP 1. 3
\fBfasremoteip\fP\&. Not set (defaults to the gateway ip address).
.IP 2. 3
\fBfas_secure_enable\fP\&. Not set (defaults to enabled).
.UNINDENT
.UNINDENT
.SS What Does the Default PreAuth Login Script Do?
.sp
\fBThe Default PreAuth Login is a shell script\fP
.sp
It is located at /usr/lib/opennds/login.sh.
.sp
It generates html output for openNDS to serve as a dynamic splash page.
.SS Login Mode
.sp
The default script has two modes of operation set by the value of the login_option_enabled config option.
.sp
The default mode is "login_option_enabled" set to "0". In this mode the initial page served to clients is a simple "Click to Continue" page.
.sp
If "login_option_enabled" is set to "1"  asks the client user to enter their name and email address. On entering this information the client user then clicks or taps "Continue".
.sp
In both cases, the script then generates a second page for openNDS to serve a  "Thankyou" page. It then adds a log entry ( /tmp/ndslog.log ), recording the client authentication details.
.sp
On tapping "Continue" for the second time, the client user is given access to the Internet.
.SS Customising the default login script
.sp
\fBStatic Mode Switching\fP
.sp
The login mode provided by the "login_option_enabled" option can be any integer value and is passed to the login script. This is used in the default login.sh to determine which type of "splash page" to serve, in the standard case either "Continue" or "Username/Email"
.sp
Additional modes could be added to the login.sh script to determine custom modes of operation.
.sp
\fBDynamic Response\fP
.sp
The script could modified to ask for any response from the client and conduct its own authentication procedures \- entirely at the discretion of the person setting up their own captive portal functionality. Looking at the details of the default login.sh will show how this is done.
.sp
An example file "multifieldlogin.sh" is provided in the source code:
.sp
\fIhttps://github.com/opennds/opennds/archive/master.zip\fP
.sp
and extracting from the folder:
.INDENT 0.0
.INDENT 3.5
"forward_authentication_service/PreAuth/"
.UNINDENT
.UNINDENT
.SS PreAuth with Remote Images
.sp
An additional example PreAuth script, login\-remote\-image.sh, is available in the source code:
.INDENT 0.0
.INDENT 3.5
\fIhttps://github.com/opennds/opennds/archive/master.zip\fP
.UNINDENT
.UNINDENT
.sp
and extracting from the folder:
.INDENT 0.0
.INDENT 3.5
"forward_authentication_service/PreAuth/"
.UNINDENT
.UNINDENT
.sp
This is based on an earlier version of the preinstalled login.sh, giving an example of how to display images pulled in from remote web servers, both http and https.
.sp
The example displays the openNDS avatar image dynamically retrieved from Github.
.SS Example of Multi Field Login
.sp
An additional example PreAuth script, multifieldlogin.sh, is available in the source code:
.INDENT 0.0
.INDENT 3.5
\fIhttps://github.com/opennds/opennds/archive/master.zip\fP
.UNINDENT
.UNINDENT
.sp
and extracting from the folder:
.INDENT 0.0
.INDENT 3.5
"forward_authentication_service/PreAuth/"
.UNINDENT
.UNINDENT
.sp
This is based on an earlier version of the preinstalled login.sh, giving an example of how to add multiple fields of information to be requested from the client.
.INDENT 0.0
.TP
.B The example displays a login form requesting the client to enter:
.INDENT 7.0
.IP \(bu 2
Username
.IP \(bu 2
Phone
.IP \(bu 2
Address
.IP \(bu 2
Access Code
.UNINDENT
.UNINDENT
.SS Writing A PreAuth Script
.sp
A Preauth script can be written as a shell script or any other language that the system has an interpreter for. It could also be a complied program.
.sp
openNDS calls the PreAuth script with a command line equivalent to an html query string but with ", " (comma space) in place of "&" (ampersand).
.sp
Full details are included in the default script login.sh.
.SS Defining and Using Variables
.sp
A Dynamic set of variables can be defined in the PreAuth dialogue and used for authentication verification purposes and/or logging.
.sp
\fBThis is not the same as\fP, and must not be confused with, Custom Parameters. Custom parameters are statically defined by the openNDS configuration and can be read directly by the PreAuth script if required.
.sp
In the login.sh script we want to ask the client user for their username and email address.
.sp
We could ask for anything we like and add our own variables to the html forms we generate.
.sp
If we want to show a sequence of forms or information pages we can do this easily.
.sp
To return to the script and show additional pages, the form action must be set to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<form action=\e"/opennds_preauth/\e" method=\e"get\e">
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: In a shell script, quotes ( " ) must be escaped with the
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"\e"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
character.
.sp
Any variables we need to preserve and pass back to ourselves or NDS must be added to the form as hidden:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<input type=\e"hidden\e" name=......
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Such variables will appear in the query string when NDS re\-calls this script.
.sp
We can then parse for them again.
.sp
When the logic of this script decides we should allow the client to access the Internet we inform NDS with a final page displaying a continue button with the form action set to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"<form action=\e"/opennds_auth/\e" method=\e"get\e">"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
We must also send NDS the client token as a hidden variable, but first we must obtain the token from ndsctl using a suitable command such as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tok="$(ndsctl json $clientip | grep token | cut \-c 10\- | cut \-c \-8)"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In a similar manner we can obtain any client or NDS information that ndsctl provides.
.sp
The query string NDS sends to us will always be of the following form (with a "comma space" separator):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
?clientip=[clientipaddress], gatewayname=[gatewayname],  redir=[originalurl], var4=[data], var5=[data], var6......
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The first three variables will be clientip, gatewayname and redir
.sp
(Note: In login.sh, we have chosen to name redir as $requested as it is actually the originally requested url.)
.sp
There is one exception to the normal sequence. If the client presses "back" on their browser, openNDS detects this and tells us by returning status=authenticated instead of redir=[originalurl]
.sp
If we detect "status" in the query string, we show a page telling the client they are already logged in.
.sp
Additional variables returned by NDS will be those we define here and send to NDS via an html form method=get
.sp
There is no limit to the number of variables we can define dynamically as long as the query string does not exceed 2048 bytes.
.sp
The query string will be truncated if it does exceed this length.
.SH BINAUTH OPTION
.SS Overview
.sp
\fBBinAuth provides a method of running a post authentication script\fP or extension program. BinAuth is ALWAYS local to NDS and as such will have access to all the resources of the local system.
.sp
\fBBinAuth works with, but does not require FAS\fP and in a simple system can be used to provide site\-wide username/password access.
.sp
\fIBinAuth is available when FAS is used at all levels of fas_secure_enabled (0, 1, 2 and 3).\fP
.sp
\fBWith FAS, a custom variable is forwarded to BinAuth\fP This can contain an embedded payload of custom data defined by the FAS. As FAS is typically remote from the NDS router, this provides a link to the local system.
.sp
\fBBinAuth has the means to set session timeout, data rate and data volume quotas\fP on a client by client basis.
.sp
\fBBinAuth is called by NDS at the following times:\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
After the client CPD browser makes an authentication request to NDS
.IP \(bu 2
After the client device is granted Internet access by NDS
.IP \(bu 2
After the client is deauthenticated by request
.IP \(bu 2
After the client idle timeout interval has expired
.IP \(bu 2
After the client session timeout interval has expired
.IP \(bu 2
After a data upload or download quota has been exceeded
.IP \(bu 2
After the client is authenticated by ndsctl command
.IP \(bu 2
After the client is deauthenticated by ndsctl command
.IP \(bu 2
After NDS has received a shutdown command
.UNINDENT
.UNINDENT
.UNINDENT
.SS BinAuth Command Line Arguments
.sp
When OpenNDS calls the configured BinAuth script, it sends a set of command line arguments depending on the reason for the call.
.SS BinAuth Command Methods
.sp
The first argument, arg[1], is always the "method".
.INDENT 0.0
.TP
.B The method will be set to one of the following values:
.INDENT 7.0
.IP \(bu 2
"\fBauth_client\fP" This is a request for authentication by the client.
.IP \(bu 2
"\fBclient_auth\fP" This is an acknowledgement of successful authentication by NDS.
.IP \(bu 2
"\fBclient_deauth\fP" This is an acknowledgement that the client has been deauthenticated by NDS.
.IP \(bu 2
"\fBidle_deauth\fP" \- NDS has deauthenticated the client because the idle timeout duration has been exceeded.
.IP \(bu 2
"\fBtimeout_deauth\fP" \- NDS has deauthenticated the client because the session length duration has been exceeded.
.IP \(bu 2
"\fBdownquota_deauth\fP" \- NDS has deauthenticated the client because the client\(aqs download quota has been exceeded
.IP \(bu 2
"\fBupquota_deauth\fP" \- NDS has deauthenticated the client because the client\(aqs upload quota has been exceeded
.IP \(bu 2
"\fBndsctl_auth\fP" \- NDS has authorised the client because of an ndsctl command (most commonly sent by the NDS AuthMon daemon).
.IP \(bu 2
"\fBndsctl_deauth\fP" \- NDS has deauthenticated the client because of an ndsctl command.
.IP \(bu 2
"\fBshutdown_deauth\fP" \- NDS has deauthenticated the client because it received a shutdown command.
.UNINDENT
.UNINDENT
.sp
Additional arguments depend on the method type:
.SS Method auth_client
.sp
The first argument is auth_client and the following arguments are set to:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
arg[2] = client_mac
.IP \(bu 2
arg[3] = username
.IP \(bu 2
arg[4] = password
.IP \(bu 2
arg[5] = url\-escaped redir variable (the URL originally requested by the client.
.IP \(bu 2
arg[6] = url\-escaped client user agent string
.IP \(bu 2
arg[7] = client_ip
.IP \(bu 2
arg[8] = client_token
.IP \(bu 2
arg[9] = url\-escaped custom variable string
.UNINDENT
.UNINDENT
.UNINDENT
.SS Method ndsctl_auth
.sp
The first argument is ndsctl_auth and the following arguments are set to:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
arg[2] = client_mac
.IP \(bu 2
arg[3] = bytes_incoming (set to 0, reserved for future use)
.IP \(bu 2
arg[4] = bytes_outgoing (set to 0, reserved for future use)
.IP \(bu 2
arg[5] = session_start \- the session start time
.IP \(bu 2
arg[6] = session_end \- the session end time
.IP \(bu 2
arg[7] = client_token
.IP \(bu 2
arg[8] = url\-escaped custom variable string
.UNINDENT
.UNINDENT
.UNINDENT
.SS All Other Methods
.sp
When the first argument is other than auth_client or ndsctl_auth, the following arguments are set to:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
arg[2] = client_mac
.IP \(bu 2
arg[3] = bytes_incoming (total incoming bytes for client)
.IP \(bu 2
arg[4] = bytes_outgoing (total incoming bytes for client)
.IP \(bu 2
arg[5] = session_start \- the session start time
.IP \(bu 2
arg[6] = session_end \- the session end time
.IP \(bu 2
arg[7] = client_token
.UNINDENT
.UNINDENT
.UNINDENT
.SS Using the Custom Variable string
.sp
Method auth_client \- arg[9] contains the url\-escaped custom variable string. openNDS extracts this variable from the query string of the http auth_client call from a FAS or Templated splash page.
.sp
It is provided for general unspecified use and is url\-escaped.
A typical example of its use is for a level 0, 1, or 2 FAS to communicate quota values for individual clients, or groups of clients.
.SS Example BinAuth Scripts
.sp
Two example BinAuth scripts are included in the source files available for download at:
\fI\%https://github.com/opennds/opennds/releases\fP
.sp
Both of them are preinstalled and ready to be enabled in the config file.
.sp
In addition, the files can be extracted from the downloaded release archive file and reside in the folder:
.sp
\fI/opennds\-[*version*]/forward_authentication_service/binauth\fP
.SS Example 1 \- Sitewide Username/Password
.sp
This example is a script designed to be used with or without FAS and provides site wide Username/Password login for groups of users, in this case "staff", "guest" and "member" with corresponding sets of credentials. If used without FAS, a special html splash page must be installed, otherwise FAS must forward the required username and password variables.
.SS Manual Installation (Example 1)
.sp
\fBThe binauth_sitewide example is pre\-installed.\fP However, a manual installation is described here by way of example to aid developers in understanding the procedure required for installing their own scripts.
The binauth_sitewide script actually has three components, the binauth script itself, an associated html file and a user database file.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
binauth_sitewide.sh
.IP \(bu 2
splash_sitewide.html
.IP \(bu 2
userlist.dat
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The file binauth_sitewide.sh should be copied to a suitable location on the NDS router, eg \fI/usr/lib/opennds/\fP
.sp
The file splash_sitewide.html should be copied to \fI/etc/opennds/htdocs/\fP
.sp
The file userlist.dat should be copied to \fI/etc/opennds/\fP
.sp
Assuming FAS is not being used, NDS is then configured by setting the BinAuth and SplashPage options in the config file (/etc/config/opennds on Openwrt, or /etc/opennds/opennds.conf on other operating systems.
.sp
On OpenWrt this is most easily accomplished by issuing the following commands:
.INDENT 0.0
.INDENT 3.5
\fIuci set opennds.@opennds[0].splashpage=\(aqsplash_sitewide.html\(aq\fP
.sp
\fIuci set opennds.@opennds[0].binauth=\(aq/usr/lib/opennds/binauth_sitewide.sh\(aq\fP
.sp
\fIuci commit opennds\fP
.UNINDENT
.UNINDENT
.sp
The script file must be executable and is flagged as such in the source archive. If necessary set using the command:
.INDENT 0.0
.INDENT 3.5
\fIchmod u+x /usr/lib/opennds/binauth_sitewide.sh\fP
.UNINDENT
.UNINDENT
.sp
This script is then activated with the command:
.INDENT 0.0
.INDENT 3.5
\fIservice opennds restart\fP
.UNINDENT
.UNINDENT
.SS Example 2 \- Local NDS Access Log
.sp
This example is a script designed to be used with or without FAS and provides local NDS logging. FAS is often remote from the NDS router and this script provides a simple method of interacting directly with the local NDS. FAS can send custom data to Binauth as a payload in the custom variable parameter that is relayed to BinAuth by NDS.
.sp
The log file is stored by default in the /tmp/ndslog/ directory.
This works for many operating systems including OpenWrt.
.sp
The location however must be changed on some operating systems, such as Debian and its variants (eg Raspbian). Here a default location of /run/ndslog/ works well.
.sp
The log location is simply changed by editing variables at the beginning of the script file.
.sp
Free space checking is done and if the log file becomes too large, logging ceases and an error is sent to syslog.
.sp
Log files do not persist through a reboot so it would be sensible to change the location of the log file to a USB stick for example.
.SS Using Example 2
.sp
\fBThe binauth_log example is pre\-installed.\fP
.sp
This script has a single component, the shell script.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
binauth_log.sh
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The file binauth_log.sh is preinstalled in the /usr/lib/opennds directory.
.sp
This is enabled by setting the BinAuth option in the config file (/etc/config/opennds on Openwrt, or /etc/opennds/opennds.conf on other operating systems.
.sp
This script is then activated with the command:
.INDENT 0.0
.INDENT 3.5
\fIservice opennds restart\fP
.UNINDENT
.UNINDENT
.SH LIBRARY UTILITIES
.SS Overview
.sp
A number of library utilities are included. These may be used by NDS itself, FAS and Preauth. These may in the future, be enhanced, have additional functionality added.
.sp
By default, library utilities will be installed in the folder
.sp
\fB/usr/lib/opennds/\fP
.SS List of Library Utilities
.SS get_client_token.sh
.sp
This utility allows the unique token of a client to be determined from the client ip address.
.sp
It can be used in PreAuth and local FAS scripts.
.INDENT 0.0
.INDENT 3.5
Usage: get_client_token.sh [clientip]
.sp
Returns: [client token]
.INDENT 0.0
.TP
.B Where:
[client token] is the unique client token string.
.UNINDENT
.UNINDENT
.UNINDENT
.SS get_client_interface.sh
.sp
This utility allows the interface a client is using to be determined from the client mac address.
.sp
It can be used in PreAuth and local FAS scripts.
.sp
It is used by NDS when fas secure levels 1 and 2 are set along with faskey also being set.
.sp
Its output is sent to FAS in the encrypted query string as the variable "clientif"
.INDENT 0.0
.INDENT 3.5
Usage: get_client_interface.sh [clientmac]
.sp
Returns: [local_interface] [meshnode_mac] [local_mesh_interface]
.sp
Where:
.INDENT 0.0
.INDENT 3.5
[local_interface] is the local interface the client is using.
.sp
[meshnode_mac] is the mac address of the 802.11s meshnode the client is using (null if mesh not present).
.sp
[local_mesh_interface] is the local 802.11s interface the client is using (null if mesh not present).
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS unescape.sh
.sp
This utility allows an input string to be unescaped. It currently only supports url\-decoding.
.sp
It can be used by NDS as the unescape callback for libmicrohttpd.
.sp
To enable, set the unescape_callback_enabled option to "1"
.sp
To disable, set the unescape_callback_enabled option to "0"
.sp
The default is disabled (use internal MHD unescape)
.sp
eg In the OpenWrt configuration file
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
\fBoption unescape_callback_enabled \(aq0\(aq\fP
.UNINDENT
.UNINDENT
.sp
Usage: unescape.sh [\-option] [escapedstring]
.sp
Returns: [unescapedstring]
.sp
Where:
.INDENT 0.0
.INDENT 3.5
[\-option] is unescape type, currently \-url only
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH DATA QUOTAS AND TRAFFIC SHAPING
.SS Data volume and Rate Quotas
.sp
openNDS (NDS) has built in \fIData Volume\fP and \fIData Rate\fP quota support.
.sp
Data volume and data rate quotas can be set globally in the config file.
.sp
The global values can be overridden on a client by client basis as required.
.SS Global Data Volume Quota
.sp
If a client exceeds the global data volume quota, or the individual client quota, that client will be forced out by deauthentication.
To continue, the client must re\-authenticate.
.SS Configuring Data Volume Quotas
.sp
Global volume quotas are configured in the config file.
.sp
\fBExample UCI configuration options:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# If the client data quota exceeds the value set here, the client will be forced out
# Values are in kB
# If set to 0, there is no limit
# Integer values only
#
option uploadquota \(aq0\(aq
option downloadquota \(aq0\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: upload means to the Internet, download means from the Internet
.sp
\fBQuotas for individual clients\fP will override configured global values and are set either by BinAuth or the Authmon Daemon (fas_secure_enable level 3) \- see example BinAuth script (binauth_log.sh) and example FAS script (fas\-aes\-https.php).
.SS Global Data Rate Quota
.sp
A rate quota is a moving average data rate.
.sp
The average is calculated  over a configured time window.
.sp
If a client exceeds the global data rate quota, or the individual client quota, that client will be blocked for a configured interval before being allowed to continue automatically.
.sp
As the Data Rate Quota is a moving average, clients are able to transfer data at the maximum rate the router can achieve for short bursts.
.sp
Data Rate Quotas are ideal for allowing opening of web pages and emails etc in the fastest way possible, yet preventing an individual client from monopolizing all the available bandwidth by streaming or transferring large files.
.SS Configuring Data Rate Quotas
.sp
Global Data Rate quotas are configured in the config file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: upload means to the Internet, download means from the Internet
# Defaults 0
# Integer values only
#
# If the client average data rate exceeds the value set here, the client will be blocked
# Values are in kb/s
# If set to 0, there is no limit
#
# Quotas and rates can also be set by FAS via Authmon Daemon, by BinAuth, and by ndsctl auth.
# Values set by these methods, will be override values set in this config file.
#
option uploadrate \(aq0\(aq
option downloadrate \(aq0\(aq
###########################################################################################
# The client data rate is calculated using a moving average.
# This allows clients to burst at maximum possible rate, only blocking if the moving average
# exceeds the specified upload or download rate.
# The moving average window size is equal to ratecheckwindow times checkinterval (seconds)
# Default 2
option ratecheckwindow \(aq2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: upload means to the Internet, download means from the Internet
.SS Data Rate Quotas for Individual Clients
.sp
\fBData Rate Quotas for individual clients\fP will override configured global values and are set either by BinAuth or the Authmon Daemon (fas_secure_enable level 3) \- see example BinAuth script (binauth_log.sh) and example FAS script (fas\-aes\-https.php).
.SS FAS Level 3
.sp
FAD level 3 uses the Authmon daemon to set quota values determined by the FAS. The example script fas\-aes\-https.php shows how to implement this.
.SS FAS level 0,2 and 2
.sp
These levels use BinAuth to set quota values determined by the FAS. The FAS would utilise the BinAuth custom variable to send quota values to a BinAuth script configured to interpret the data passed to it in the variable. There is no set method for doing this, it is left to individual installers to develop their own method.
.SS Traffic Shaping
.sp
openNDS (NDS) supports Traffic Shaping (Bandwidth Limiting) using the SQM \- Smart Queue Management (sqm\-scripts) package, available for OpenWrt and generic Linux.
.sp
\fI\%https://github.com/tohojo/sqm\-scripts\fP
.sp
SQM does efficient bandwidth control, independently for both upload and download, on an IP connection basis. This ideal for enforcing a fair usage policy on a typical Captive Portal implementation.
.sp
In addition the Queue management SQM provides, results in significantly improved WiFi performance, particularly on the modern low cost WiFi routers available on the market today.
.sp
Finally, SQM controls quality of service (QOS), allowing priority for real time protocols such a VOIP.
.sp
Overall, SQM can enhance significantly the experience of clients using your Captive Portal, whilst ensuring a single client is unlikely to dominate the available Internet service at the expense of others.
.SS Installing SQM
.sp
The generic Linux scripts can be downloaded from the link above.
.sp
\fBOn OpenWrt\fP, SQM can be installed from the LuCi interface or by the following CLI commands on your router:
.sp
\fIopkg update\fP
.sp
\fIopkg install sqm\-scripts\fP
.sp
\fBNote\fP:
The standard and default SQM installation expects monitoring of the interface connecting to the WAN. What we need is for SQM to monitor the interface NDS is bound to. This of course will be a LAN interface.
The default configuration will limit bandwidth from the WAN connection to services on the Internet. Our configuration will limit client bandwidth TO NDS, thus enabling a true fair usage policy.
.sp
\fITo prevent confusion\fP it is important to understand that SQM defines "Upload" as traffic "Out" of the interface SQM is monitoring and "Download" as traffic "In" to the SQM interface.
.sp
In the default SQM configuration, Upload will mean what is normally accepted, ie traffic to the Internet and Download will mean traffic from the Internet.
.sp
\fBIn our case however the terms will be reversed!\fP
.sp
The default SQM configuration file on OpenWrt is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
config queue
    option enabled \(aq0\(aq
    option interface \(aqeth1\(aq
    option download \(aq85000\(aq
    option upload \(aq10000\(aq
    option qdisc \(aqfq_codel\(aq
    option script \(aqsimple.qos\(aq
    option qdisc_advanced \(aq0\(aq
    option ingress_ecn \(aqECN\(aq
    option egress_ecn \(aqECN\(aq
    option qdisc_really_really_advanced \(aq0\(aq
    option itarget \(aqauto\(aq
    option etarget \(aqauto\(aq
    option linklayer \(aqnone\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For simple rate limiting, we are interested in setting the desired interface and the download/upload rates.
.sp
We may also want to optimize for the type of Internet feed and change the qdisc.
.sp
A typical Internet feed could range from a high speed fiber optic connection through fast VDSL to a fairly poor ADSL connection and configured rates should be carefully chosen when setting up your Captive Portal.
.sp
A typical Captive Portal however will be providing free Internet access to customers and guests at a business or venue, using their mobile devices.
.sp
A good compromise for a business or venue might be a download rate from the Internet of ~3000 Kb/s and an upload rate to the Internet of ~1000 Kb/s will be adequate, allowing for example, a client to stream a YouTube video, yet have minimal effect on other clients browsing the Internet or downloading their emails. Obviously the values for upload and download rates for best overall performance depend on many factors and are best determined by trial and error.
.sp
If we assume we have NDS bound to interface br\-lan and we have a VDSL connection, a good working setup for SQM will be as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fIRate to\fP Internet 1000 Kb/s (but note this is from the perspective of the interface SQM is monitoring, so this means DOWNLOAD from the client).
.IP \(bu 2
\fIRate from\fP Internet 3000 Kb/s (also note this is from the perspective of the interface SQM is monitoring, so is means UPLOAD to the client).
.IP \(bu 2
\fIVDSL\fP connection (usually an ethernet like connection)
.IP \(bu 2
\fINDS\fP bound to br\-lan
.UNINDENT
.UNINDENT
.UNINDENT
.sp
We will configure this by issuing the following commands:
.sp
\fINote the reversed "upload" and "download" values.\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci set sqm.@queue[0].interface=\(aqbr\-lan\(aq

uci set sqm.@queue[0].download=\(aq1000\(aq

uci set sqm.@queue[0].upload=\(aq3000\(aq

uci set sqm.@queue[0].linklayer=\(aqethernet\(aq

uci set sqm.@queue[0].overhead=\(aq22\(aq

uci set sqm.@queue[0].qdisc=\(aqcake\(aq

uci set sqm.@queue[0].script=\(aqpiece_of_cake.qos\(aq

uci set sqm.@queue[0].enabled=\(aq1\(aq

uci commit sqm

service sqm restart
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Replace the linklayer and overhead values to match your Internet feed.
.sp
The following table lists LinkLayer types and Overhead for common feed types:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|l|.
_
T{
Connection Type
T}	T{
LinkLayer
T}	T{
Overhead
T}
_
T{
Fibre/Cable
T}	T{
Ethernet
T}	T{
18
T}
_
T{
VDSL2
T}	T{
Ethernet
T}	T{
22
T}
_
T{
Ethernet
T}	T{
Ethernet
T}	T{
38
T}
_
T{
ADSL/DSL
T}	T{
ATM
T}	T{
44
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
Some broadband providers use variations on the values shown here, contacting them for details sometimes helps but often the request will be "off script" for a typical helpdesk. These table values should give good results regardless. Trial and error and the use of a good speed tester is often the only way forward.
A good speed tester web site is \fI\%http://dslreports.com/speedtest\fP
.sp
Further details about SQM can be found at the following links:
.sp
\fI\%https://openwrt.org/docs/guide\-user/network/traffic\-shaping/sqm\fP
.sp
\fI\%https://openwrt.org/docs/guide\-user/network/traffic\-shaping/sqm\-details\fP
.SH WALLED GARDEN
.SS Manual Walled Garden
.sp
Preauthenticated clients are, by default, blocked from all access to the Internet.
.sp
Access to certain web sites can be allowed. For example, clients will automatically be granted access to an external FAS server for the purpose of authentication.
.sp
Access to other web sites may be manually granted so clients can be served content such as news, information, advertising, etc. This is achieved in openNDS by allowing access to the IP address of the web sites as required.
.sp
A set of such web sites is referred to as a Walled Garden.
.SS Autonomous Walled Garden
.sp
Granting access by specifying the site IP address works well in the simplest of cases but the administrative overhead can rapidly become very difficult, for example with social media sites that load balance high volumes of traffic over many possible IP addresses.
.sp
In addition, the IP address of any web site may change.
.sp
Rather than using IP addresses, a much more efficient method of granting access would be by using the Fully Qualified Domain Name (FQDN) of each site and have a background process populate a database of allowed IP addresses.
.sp
openNDS supports Autonomous Walled Garden by means of a simple configuration option. This does have additional dependencies but these only apply if the Autonomous Walled Garden is enabled.
.SS OpenWrt Walled Garden
.sp
The additional dependencies are the ipset and dnsmasq\-full packages.
Install these by running the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
opkg update
opkg install ipset
opkg remove dnsmasq
opkg install dnsmasq\-full
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Configure as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci add_list opennds.@opennds[0].walledgarden_fqdn_list=\(aq<fqdn1> <fqdn2> <fqdn3> [......] <fqdnN>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where <fqdn1> to <fqdnN> are the fully qualified domain names of the URLs you want to use to populate the ipset.
.sp
eg. For Facebook use facebook.com and fbcdn.net as fqdn1 and fqdn2
.sp
In addition you can limit access to the Walled Garden to a list of IP ports:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci add_list opennds.@opennds[0].walledgarden_port_list=\(aq<port1> <port2> <port3> [......] <portN>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Restart openNDS to activate the Walled Garden.
.sp
To make these changes permanent (eg survive a reboot), run the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci commit opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Generic Linux Walled Garden
.sp
On most generic Linux platforms the procedure is in principle the same as for OpenWrt.
.sp
The ipset and full dnasmasq packages are requirements.
.sp
You can check the compile time options of dnsmasq with the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dnsmasq \-\-version | grep \-m1 \(aqCompile time options:\(aq | cut \-d: \-f2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the returned string contains "no\-ipset" then you will have to upgrade dnsmasq to the full version.
.sp
To enable Walled Garden, add the following to the /etc/opennds/opennds.conf file
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
walledgarden_fqdn_list <fqdn1> <fqdn2> <fqdn3> [......] <fqdnN>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In addition you can specify a restricted set of ports for access to the walled garden by adding the line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
walledgarden_port_list <port1> <port2> <port3> [......] <portN>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Restart openNDS to activate the Walled Garden.
.SH USING NDSCTL
.sp
A openNDS install includes ndsctl, a separate application which provides some control over a running openNDS process by communicating with it over a unix socket. Some command line options:
.INDENT 0.0
.IP \(bu 2
To print to stdout some information about your openNDS process:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl status\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To print to stdout the list of clients in human readable format:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl clients\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To print to stdout the list of clients and trusted devices in json format:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl json\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To print to stdout the details of a particular client in json format (This is particularly useful if called from a FAS or Binauth script.):
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl json [mac|ip|token]\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To block a MAC address, when the MAC mechanism is block:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl block MAC\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To unblock a MAC address, when the MAC mechanism is block:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl unblock MAC\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To allow a MAC address, when the MAC mechanism is allow:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl allow MAC\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To unallow a MAC address, when the MAC mechanism is allow:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl unallow MAC\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To deauthenticate a currently authenticated user given their IP or MAC
address:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl deauth IP|MAC\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
To set the verbosity of logged messages to n:
.INDENT 2.0
.INDENT 3.5
\fB/usr/bin/ndsctl debuglevel n\fP
.UNINDENT
.UNINDENT
.INDENT 2.0
.IP \(bu 2
debuglevel 0 : Silent (only LOG_ERR and LOG_EMERG messages will be seen, otherwise there will be no logging.)
.IP \(bu 2
debuglevel 1 : LOG_ERR, LOG_EMERG, LOG_WARNING and LOG_NOTICE (this is the default level).
.IP \(bu 2
debuglevel 2 : debuglevel 1 + LOG_INFO
.IP \(bu 2
debuglevel 3 : debuglevel 2 + LOG_DEBUG
.UNINDENT
.sp
All other levels are undefined and will result in debug level 3 being set.
.UNINDENT
.sp
For more options, run ndsctl \-h. (Note that if you want the effect of ndsctl commands to to persist across openNDS restarts, you have to edit the configuration file.)
.SH CUSTOMISING OPENNDS
.sp
After initial installation, openNDS (NDS) should be working in its most basic mode and client Captive Portal Detection (CPD) should pop up the default Click to Continue page.
.sp
Before attempting to customise NDS you should ensure it is working in this basic mode before you start.
.sp
NDS reads its configuration file when it starts up but the location of this file varies depending on the operating system.
.sp
As NDS is a package that requires hardware configured as an IP router, perhaps the most common installation is using OpenWrt. However NDS can be compiled to run on most Linux distributions, the most common being Debian or one of its popular variants (eg Raspbian).
.sp
If NDS is working in the default, post installation mode, then you will have met the NDS dependencies and can now move on to your own customisation.
.SS Rules for Customised Splash Pages
.sp
It should be noted when designing a custom splash page that for security reasons many client device CPD implementations:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Immediately close the browser when the client has authenticated.
.IP \(bu 2
Prohibit the use of href links.
.IP \(bu 2
Prohibit downloading of external files (including .css and .js, even if they are allowed in NDS firewall settings).
.IP \(bu 2
Prohibit the execution of javascript.
.UNINDENT
.UNINDENT
.UNINDENT
.SS The Configuration File
.sp
In OpenWrt, or operating systems supporting UCI (such as LEDE) the configuration is kept in the file:
.INDENT 0.0
.INDENT 3.5
\fB/etc/config/opennds\fP
.UNINDENT
.UNINDENT
.sp
In other operating systems the configuration is kept in the file:
.INDENT 0.0
.INDENT 3.5
\fB/etc/opennds/opennds.conf\fP
.UNINDENT
.UNINDENT
.sp
Both of these files contain a full list of options and can be edited directly. A restart of NDS is required for any changes to take effect.
.sp
In the case of OpenWrt though, once you are confident in your configuration requirements you can use UCI to read and set any of the configuration options using simple commands, making this very convenient if making changes from scripts, such as those you may write to use with Binauth and FAS.
.sp
For example, to list the full configuration, at the command line type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci show opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To display the Gateway Name, type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci get opennds.@opennds[0].gatewayname
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To set the Gateway Name to a new value, type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci set opennds.@opennds[0].gatewayname=\(aqmy new gateway\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To add a new firewall rule allowing access to another service running on port 8888 on the router, type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci add_list opennds.@opennds[0].users_to_router=\(aqallow
tcp port 8888\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally you must tell UCI to commit your changes to the configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci commit opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The Legacy Click and Go Splash Page
.sp
\fBThe legacy Click to Continue html splash page is deprecated and disabled.
It will be removed entirely in later releases.\fP
.INDENT 0.0
.TP
.B To allow time for migration, this can be re\-enabled by setting options:
allow_legacy_splash = \(aq1\(aq and
login_option_enabled = "0" (default)
.sp
The legacy splash page can be found at:
.INDENT 7.0
.INDENT 3.5
\fB/etc/opennds/htdocs/splash.html\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
When the splash page is served, the following variables in the page are
replaced by their values:
.INDENT 0.0
.IP \(bu 2
\fI$gatewayname\fP The value of GatewayName as set in opennds.conf.
.IP \(bu 2
\fI$authtarget\fP A URL which encodes a unique token and the URL of the user\(aqs   original web request. If opennds receives a request at this URL, it completes the authentication process for the client and replies to the request with a "302 Found" to the encoded originally requested URL.
.sp
It should be noted however that, depending on vendor, the client\(aqs built in CPD may not respond to simple html links.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
An href link example that my prove to be problematical:
.INDENT 0.0
.INDENT 3.5
\fB<a href="$authtarget">Enter</a>\fP
.UNINDENT
.UNINDENT
.sp
(You should instead use a GET\-method HTML form to send this   information to the opennds server; see below.)
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI$tok\fP, \fI$redir\fP, \fI$authaction\fP, and \fI$denyaction\fP are available and should be used to write the splash page to use a GET\-method HTML form instead of using $authtarget as the value of an href attribute to communicate with the opennds server.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
\fI$authaction\fP and \fI$denyaction\fP are virtual urls used to inform NDS that a client should be authenticated or deauthenticated and are of the form:
.sp
\fIhttp://gatewayaddress:gatewayport/opennds_auth/\fP
.sp
and
.sp
\fIhttp://gatewayaddress:gatewayport/opennds_deny/\fP
.sp
A simple example of a GET\-method form:
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<form method=\(aqGET\(aq action=\(aq$authaction\(aq>
  <input type=\(aqhidden\(aq name=\(aqtok\(aq value=\(aq$tok\(aq>
  <input type=\(aqhidden\(aq name=\(aqredir\(aq value=\(aq$redir\(aq>
  <input type=\(aqsubmit\(aq value=\(aqClick Here to Enter\(aq>
</form>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI$clientip\fP, \fI$clientmac\fP and \fI$gatewaymac\fP The respective addresses
of the client or gateway. This might be useful in cases where the data
needs to be forwarded to some other place by the splash page itself.
.IP \(bu 2
\fI$nclients\fP and \fI$maxclients\fP User stats. Useful when you need to
display something like "n of m users online" on the splash site.
.IP \(bu 2
\fI$uptime\fP The time opennds has been running.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
A list of all available variables are included in the splash.html file.
.sp
If the user accesses the virtual url \fI$authaction\fP when already authenticated, a status page is shown:
.sp
\fB/etc/opennds/htdocs/status.html\fP
.sp
In the status.html file, the same variables as in the splash.html site can be used.
.UNINDENT
.UNINDENT
.sp
It should be noted when designing a custom splash page that for security reasons many client device CPD implementations:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Immediately close the browser when the client has authenticated.
.IP \(bu 2
Prohibit the use of href links.
.IP \(bu 2
Prohibit downloading of external files (including .css and .js, even if they are allowed in NDS firewall settings).
.IP \(bu 2
Prohibit the execution of javascript.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Also, note that any images you reference should reside in the subdirectory /etc/opennds/htdocs/images/.
.SS Dynamic Splash Pages
.SS Default Dynamic Click to Continue
.sp
The pre\-installed dynamic login page is enabled by setting option login_option_enabled = "0".
This is the default assuming
allow_legacy_splash = \(aq0\(aq, the default value.
.sp
It generates a Click to Continue page.
.sp
User clicks on "Continue" are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log
.sp
Where [tmpfs_dir] is the operating system "temporary" tmpfs mount point.
This will be  /tmp /run or /var and is automatically detected.
.sp
Details of how the script works are contained in comments in the script itself.
.SS Pre\-Installed User Login Dynamic Splash Page
.sp
The pre\-installed dynamic login page is enabled by setting option login_option_enabled = "1".
.sp
It generates a login page asking for username and email address.
User logins are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log
.sp
Where [tmpfs_dir] is the operating system "temporary" tmpfs mount point.
This will be  /tmp /run or /var and is automatically detected.
.sp
Details of how the script works are contained in comments in the script itself.
.SS Custom Dynamic Splash Pages
.sp
Custom designed dynamically generated splash pages are supported using FAS and PreAuth (such as the included alternative username/email login script).
.sp
For details see the FAS and PreAuth chapters.
.SH FREQUENTLY ASKED QUESTIONS
.SS What\(aqs the difference between versions?
.sp
\fBNoDogSplash and openNDS\fP are derived from the same code base.
.sp
You cannot upgrade from NoDogSplash to openNDS, instead you must first uninstall NodogSplash before installing openNDS.
.sp
\fBNoDogSplash\fP is optimised for running on devices with very limited resources and supports only a single \fIstatic\fP templated html splash page.
.sp
\fBopenNDS\fP supports dynamic html splash page generation (at default, still with minimal resource utilisation) and an API to support the coding of sophisticated Captive Portal solutions.
.sp
\fBopenNDS v5\fP This was the first release of openNDS after forking from NoDogsplash. The following enhancements are included:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBopenNDS API (FAS)\fP
.sp
A forwarding authentication service. FAS supports development of "Credential Verification" running on any dynamic web serving platform, on the same device as openNDS, on another device on the local network, or on an Internet hosted web server.
.IP \(bu 2
\fBPreAuth\fP
.sp
An implementation of FAS running on the same device as openNDS and using openNDS\(aqs own web server to generate dynamic web pages. Any scripting language or even a compiled application program can be used. This has the advantage of not requiring the resources of a separate web server.
.IP \(bu 2
\fBBinAuth\fP
.sp
Enabling an external script to be called for doing post authentication processing such as setting session durations or writing local logs.
.IP \(bu 2
\fBEnforce HTTPS option\fP
.sp
This option enables \fIhttps\fP access to a remote, Internet based FAS server, ensuring the client device does not receive any security warnings or errors. Access to the FAS server using \fBhttps\fP protocol is enforced.
.IP \(bu 2
\fBData volume and Rate Quotas\fP
.sp
This option enables built in \fIData Volume\fP and \fIData Rate\fP quota support. Data volume and data rate quotas can be set globally in the config file. The global values can be overridden on a client by client basis as required.
.IP \(bu 2
\fBIntroduction of library scripts\fP
.sp
Numerous library scripts are introduced to simplify development of applications.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBopenNDS v6\fP This is the first version of openNDS to use the updated libmicrohttpd (MHD) API introduced with v0.9.71.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
openNDS \fBREQUIRES\fP MHD v0.9.71 or higher.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBopenNDS v7\fP This version contains several major enhancements, including:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBAutonomous Walled Garden Support\fP
.sp
A simple openNDS configuration option enables Autonomous Walled Garden operation based on a list of target FQDNs
.IP \(bu 2
\fBCustom Parameter Support\fP
.sp
A list of static Custom Parameters can be set as a configuration option. Once set, these parameters are fixed and will be sent to remote FAS servers.
.sp
This functionality was added specifically to support remote configuration tools such as Opensync, but can be generally useful for passing local fixed information to a remote FAS.
.sp
It is important that this is NOT confused with the dynamic Custom Variables that can be defined as a part of a FAS/Client dialogue.
.IP \(bu 2
\fBLegacy Templated splash.html Deprecated and Disabled\fP
.sp
The legacy splash.html page and its templated variables is deprecated and disabled. This is replaced by an enhanced login option script capable of generating a dynamic html dialogue. The default is a simple click to continue page, similar to the old splash.html.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBopenNDS v8\fP This version contains several major enhancements, including:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBBase 64 encoding of the Query string\fP
.sp
The introduction of Base 64 encoding of the query string into the FAS API, enables easier customisation of FAS scripts.
.IP \(bu 2
\fBGlobal use of Hashed ID (hid)\fP
.sp
Hashed ID (hid), carried in the base64 encoded query string for levels 1, 2 and 3, including the default click to continue page, provides a uniform level of security against portal bypass. The option "faskey" is now enabled at all times with a simple default value and settable in the config files and FAS scripts.
.IP \(bu 2
\fBClient User Status Page\fP
.sp
A client user status page is now available at a configurable Gateway FQDN. This page includes a listing of the client\(aqs quota allocation and usage, as well as a "Logout" button. A client that is connected butnot logged in for any reason will be redirected to an RFC6585 Status Code 511 "Network Authentication Required" page with a "Login" button. the default url for a client to access their status page is \fI\%http://status.client\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Can I upgrade from NoDogSplash to openNDS?
.sp
No.
.INDENT 0.0
.IP \(bu 2
You must first uninstall NoDogSplash before installing openNDS.
.UNINDENT
.SS Can I upgrade from v5 to v6
.sp
Yes.
.INDENT 0.0
.IP \(bu 2
But you must upgrade libmicrohttpd to version v0.9.71 or higher.
.UNINDENT
.SS Can I upgrade from v6 to v7?
.sp
You can, if:
.INDENT 0.0
.IP \(bu 2
You don\(aqt use RedirectURL (this has been deprecated for some time as it mostly did not work with client CPD implementations. It has now been removed. A reliable replacement is a FAS Welcome Page.
.IP \(bu 2
You don\(aqt use the Templated html splash page (splash.html). Templated splash is now deprecated and disabled. It can be re\-enabled by setting the allow_legacy_splash option to allow time for migration. Support will be removed entirely in a later version.
.UNINDENT
.SS Can I upgrade from v7 to v8?
.sp
You can, if:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
You modify your FAS scripts to use the openNDS v8 API. The FAS query string is now either base64 encoded, or encrypted.
.IP \(bu 2
In addition Hashed ID (hid) is used for authentication, removing the need for a FAS script to somehow obtain the client Token.
.UNINDENT
.UNINDENT
.UNINDENT
.SS How can I add custom parameters, such as site specific information?
.sp
Custom parameters were introduced in openNDS version 7 and are defined simply in the config file. These parameters are passed to the FAS in the query string. Version 8 embeds any custom parameters in the encoded/encrypted query string, macing it much simpler to parse for them in the FAS script.
.SS How do I manage client data usage?
.sp
openNDS (NDS) has built in \fIData Volume\fP and \fIData Rate\fP quota support.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Data volume and data rate quotas can be set globally in the config file.
.IP \(bu 2
The global values can be overridden on a client by client basis as required, either by FAS or BinAuth.
.IP \(bu 2
If a client exceeds their volume quota they will be deauthenticated.
.IP \(bu 2
If a client exceeds their rate quota, they will be temporarily blocked to ensure their average rate stays below the rate quota value. This allows clients to burst at a higher rate for shot intervals, improving performance, but prevents them from hogging bandwidth.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Can I use Traffic Shaping with openNDS?
.sp
SQM Scripts (Smart Queue Management), is fully compatible with openNDS and if configured to operate on the openNDS interface (br\-lan by default) will provide efficient IP connection based traffic control to ensure fair usage of available bandwidth.
.sp
This can be installed as a package on OpenWrt.
For other distributions of Linux it is available at:
\fI\%https://github.com/tohojo/sqm\-scripts\fP
.SS Is an \fIhttps splash page\fP supported?
.sp
\fBYes\fP\&. FAS Secure Level 3 enforces https protocol for the splash login page on an external FAS server.
.SS Is \fIhttps capture\fP supported?
.sp
\fBNo\fP\&.
.INDENT 0.0
.IP \(bu 2
If it was supported, all connections would have a \fBcritical certificate failure\fP\&.
.IP \(bu 2
HTTPS web sites are now more or less a standard and to maintain security and user confidence it is essential that captive portals \fBDO NOT\fP attempt to capture port 443.
.IP \(bu 2
All modern client devices have the built in, industry standard, \fICaptive Portal Detection (CPD) service\fP\&. This is responsible for triggering the captive portal splash/login page and is \fBspecifically intended to make https capture unnecessary\fP\&.
.UNINDENT
.SS What is CPD / Captive Portal Detection?
.sp
CPD (Captive Portal Detection) has evolved as an enhancement to the network manager component included with major Operating Systems (Linux, Android, iOS/MacOS, Windows).
.INDENT 0.0
.INDENT 3.5
Using a pre\-defined port 80 web page (the one that gets used depends on the vendor) the network manager will detect the presence of a captive portal hotspot and notify the user. In addition, most major browsers now support CPD.
.UNINDENT
.UNINDENT
.SH HOW TO COMPILE OPENNDS
.SS Linux/Unix \- Compile in Place on Target Hardware
.sp
Make sure the development suite for your Linux distribution is installed.
.sp
The libmicrohttpd library (MHD) is a dependency of openNDS so compiling and installing this is a prerequisite.
.sp
\fBFirst\fP, create a working directory and "cd" into it.
.sp
\fBNext, Download and un\-tar the libmicrohttpd source files.\fP
.sp
You can find a version number for MHD at \fI\%https://ftp.gnu.org/gnu/libmicrohttpd/\fP
.sp
The version number for MHD must not exceed 0.9.70 for versions of openNDS less than 6.0.0
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd\-0.9.71.tar.gz
tar  \-xf libmicrohttpd\-0.9.71.tar.gz
cd libmicrohttpd\-0.9.71
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where "0.9.71" is the MHD version number we are using in this example.
.sp
\fBNow configure and compile:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./configure \-\-disable\-https
make
sudo rm /usr/local/lib/libmicrohttpd*
sudo make install
sudo rm /etc/ld.so.cache
sudo ldconfig \-v
cd ..
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBThen proceed to download the opennds source files.\fP
.sp
You can find a release version number for openNDS at \fI\%https://github.com/openNDS/openNDS/releases\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget https://codeload.github.com/opennds/opennds/tar.gz/v7.0.1
tar \-xf v7.0.1
cd openNDS\-7.0.1
make
sudo make install
sudo systemctl enable opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where "7.0.1" is the openNDS version we are using in this example.
.sp
openNDS should now start automatically at boot time.
.sp
It can be manually started, restarted, stopped or disabled with the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo systemctl start opennds

sudo systemctl restart opennds

sudo systemctl stop opennds

sudo systemctl disable opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The status of openNDS can be checked with the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo ndsctl status
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On most Linux distributions you can read the last few entries for openNDS in the system message log with the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo systemctl status opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If openNDS fails to start, check for error messages with the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo journalctl \-e
.ft P
.fi
.UNINDENT
.UNINDENT
.SS OpenWrt Package
.sp
The OpenWrt package feed supports cross\-compiled openNDS packages for all OpenWrt targets. See the "Installing openNDS" section of this documentation. The latest release of openNDS will be found in OpenWrt Snapshots, but will nevertheless be a stable release.
.sp
To include openNDS into your OpenWRT image or to create an .ipk
package (similar to Debian\(aqs .deb files), you can build an OpenWRT image.
.sp
You need a Unix console to enter commands into.
.sp
Install the dependencies of the build environment (eg on Debian/Ubuntu):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install git subversion g++ libncurses5\-dev gawk zlib1g\-dev build\-essential
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Build Commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone https://git.openwrt.org/openwrt/openwrt.git
cd openwrt

\&./scripts/feeds update \-a
\&./scripts/feeds install \-a
\&./scripts/feeds uninstall opennds

git clone git://github.com/opennds/opennds.git
cp \-rf opennds/openwrt/opennds package/
rm \-rf opennds/

make defconfig
make menuconfig
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
At this point select the appropriate "Target System" and "Target Profile"
depending on what target chipset/router you want to build for.
Now select the openNDS package in "Network \-\-\-> Captive Portals".
.sp
Now compile/build everything:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The images and all ipk packages are now inside the bin/ folder.
You can install the openNDS .ipk using \fIopkg install <ipkg\-file>\fP on the router or just use the whole image.
.sp
For details please check the OpenWRT documentation.
.sp
### Note for developers
.sp
## Build Notes
.sp
You might want to use your own source location and not the remote repository.
To do this you need to checkout the repository yourself and commit your changes locally:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone git://github.com/opennds/opennds.git
cd opennds
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\&... apply your changes
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git commit \-am "my change"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now create a symbolic link in the openNDS package folder using the abolute path:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ln \-s /my/own/project/folder/opennds/.git openwrt/package/opennds/git\-src
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Also make sure to enable
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"Advanced configuration options" => "Enable package source tree override"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
in the menu when you do \fImake menuconfig\fP\&.
.SH DEBUGGING OPENNDS
.SS Syslog Logging
.sp
openNDS supports four levels of debugging to syslog.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
debuglevel 0 : Silent (only LOG_ERR and LOG_EMERG messages will be seen, otherwise there will be no logging.)
.IP \(bu 2
debuglevel 1 : LOG_ERR, LOG_EMERG, LOG_WARNING and LOG_NOTICE (this is the default level).
.IP \(bu 2
debuglevel 2 : debuglevel 1 + LOG_INFO
.IP \(bu 2
debuglevel 3 : debuglevel 2 + LOG_DEBUG
.UNINDENT
.sp
All other levels are undefined and will result in debug level 3 being set.
.UNINDENT
.UNINDENT
.sp
To see maximally verbose debugging output from openNDS, set log level to 3.
.sp
On OpenWrt, you can use the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
uci set opennds.@opennds[0].debuglevel=\(aq3\(aq
uci commit opennds
service opennds restart
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Debug messages are logged to syslog. You can view messages with the logread command.
.sp
The default level of logging is 1, and is more appropriate for routine use.
.sp
Logging level can also be set using ndsctl.
.UNINDENT
.UNINDENT
.SS Firewall Cleanup
.INDENT 0.0
.INDENT 3.5
When stopped, openNDS deletes its iptables rules, attempting to leave the router\(aqs firewall in its original state. If not (for example, if openNDS crashes instead of exiting cleanly) subsequently starting and stopping openNDS should remove its rules.
.sp
On OpenWrt, restarting the firewall will overwrite openNDS\(aqs iptables rules, so when the firewall is restarted it will automatically restart openNDS if it is running.
.UNINDENT
.UNINDENT
.SS Packet Marking
.INDENT 0.0
.INDENT 3.5
openNDS operates by marking packets. Many packages, such as mwan3 and SQM scripts, also mark packets.
.sp
By default, openNDS marks its packets in such a way that conflicts are unlikely to occur but the masks used by openNDS can be changed if necessary in the configuration file.
.UNINDENT
.UNINDENT
.SS IPtables Conflicts
.INDENT 0.0
.INDENT 3.5
Potential conflicts may be investigated by looking at your overall iptables setup. To list all the rules in all the chains, run
.INDENT 0.0
.INDENT 3.5
\fBiptables \-L\fP
.UNINDENT
.UNINDENT
.sp
For extensive suggestions on debugging iptables, see for example, Oskar Andreasson\(aqs tutorial at:
.sp
\fI\%https://www.frozentux.net/iptables\-tutorial/iptables\-tutorial.html\fP
.UNINDENT
.UNINDENT
.SH TODO LIST
.sp
Features should be aimed at providing tools to allow openNDS to be used as flexible Captive Portal engine, rather than building in specific solutions.
.sp
Here is a list of possible things TO DO
.INDENT 0.0
.IP \(bu 2
Extend Status processing to display a page when a user\(aqs authentication is rejected, e.g. because the user exceeded a quota or is blocked etc.
.IP \(bu 2
ip version 6 is not currently supported by NDS. It is not essential or advantageous to have in the short term but should be added at some time in the future.
.IP \(bu 2
Automatic Offline mode/ Built in DNS forwarder. Some thought and discussion has been put into this and it is quite possible to achieve.
.UNINDENT
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
The openNDS Contributors
.SH COPYRIGHT
2016 - 2021, The NoDogSplash and openNDS Contributors
.\" Generated by docutils manpage writer.
.
